runner.github-runner-group.bind-existing

Bind an existing GitHub organization runner group onto an Orkestia runner group without creating, moving, or recreating runners

Bind an existing GitHub organization runner group onto an Orkestia RunnerGroup.

Verifies GET /orgs/{org}/actions/runner-groups/{id} and writes the external ref. Does not create a GitHub group and does not create, move, or recreate runners.

Overview

Property	Value
Workflow type	Atomic
Library	App-runners
Version	1.0

Input Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	Yes	—	UUID of the Orkestia RunnerGroup to bind, picked from the organization's list of runner groups.
organization_uuid	uuid	Yes	—	UUID of the caller's organization, injected server-side from the authenticated request.
github_runner_group_ref	integer	Yes	—	Existing GitHub organization runner-group id (external GitHub API identifier, not an Orkestia primary key).
github_runner_group_name	string	No	—	Expected GitHub runner-group name. When set, the live GitHub name must match exactly.
actor_uuid	uuid	No	—	—

Output Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	No	—	UUID of the RunnerGroup this action operates on, picked from the organization's list of runner groups; echoed on output alongside terminal/error payloads.
organization_uuid	uuid	No	—	UUID of the caller's organization, injected server-side from the authenticated request; scopes the operation to the correct tenant. Echoed on output alongside terminal/error payloads.
runner_execution_uuid	uuid	No	—	UUID of the RunnerExecution this action operates on, picked from the organization's (optionally group-scoped) list of executions; echoed on output alongside terminal/error payloads.
workflow_uuid	string	No	—	Engine workflow-run identifier (or, for GitHub-Actions-triggered flows, an external GitHub Actions run id) associated with this record; not a platform entity foreign key despite the name. No source is attached since there is no list/query workflow for an internal run id.
status	string	No	—	—
outcome	string	No	—	—
initiated_at	string	No	—	—
completed_at	string	No	—	—
failed_at	string	No	—	—
failure_reason	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—
actor_uuid	uuid	No	—	UUID of the user or service actor who triggered this action, injected server-side from the authenticated request when available; used for audit/attribution only. Optional — omitted for system or service-triggered actions with no human actor.
reason	string	No	—	—
workflow_run_uuid	string	No	—	Engine-stamped correlation/run id for this DAG execution (ADR-015/E1 plumbing), written into state_data by action_start; not a foreign key to any business entity. No source is attached since there is no list/query workflow for an internal run id.
retry_count	integer	No	—	—
retried_from	string	No	—	—
failed_step	json	No	—	—
failed_layer	json	No	—	—
failed_at_state	json	No	—	—
compensation_trigger	json	No	—	—
comp_current_layer	json	No	—	—
comp_queue	json	No	—	—
comp_retry_count	json	No	—	—
github_runner_group_ref	integer	No	—	—
github_runner_group_name	string	No	—	—
github_runners_count	integer	No	—	—
already_bound	boolean	No	—	—
bound_at	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "runner.github-runner-group.bind-existing",
  "initial_data": {
    "runner_group_uuid": "value",
    "organization_uuid": "value",
    "github_runner_group_ref": 123
  }
}