Build and run

Runs and operations

A run is one workflow snapshot executed for one source revision and provider event. Jobs form its DAG; attempts preserve retries without erasing earlier evidence.

Run, job, attempt, step

Runnable keeps operational history immutable enough to explain what actually happened after definitions, credentials, or deployments change.

Object	Meaning
Run	The workflow, trusted source SHA/ref, trigger, actor, inputs, run name, and aggregate conclusion.
Job	A dependency node with a runner, matrix values, environment, condition, and current attempt.
Attempt	One execution of a job. Infrastructure retry or operator rerun creates new history instead of rewriting the old attempt.
Step	A shell command or resolved action with timestamps, output, exit code, conclusion, annotations, and summary.

Statuses and conclusions

Status describes lifecycle. Conclusion exists only when a run, job, attempt, or step is terminal.

Value	Meaning	Operator response
queued	Created and waiting for dependencies, environment rules, concurrency, billing, or runner admission.	Open the job reason before retrying.
in_progress	At least one admitted unit is running or reconciling.	Follow live logs or cancel if obsolete.
completed	Terminal; inspect conclusion.	No further work is scheduled for this object.
success	All required work completed successfully.	None.
failure	Workflow or action returned a failing result.	Fix source/configuration, or rerun if transient.
cancelled	Cancelled by a user, agent, concurrency rule, or parent run.	Dispatch or rerun only if still needed.
skipped	Condition or dependency result prevented execution.	Inspect if and needs expressions.
timed_out	Job or step exceeded its configured limit, at most six hours.	Reduce the task or timeout source of waiting.
infrastructure_failure	Runner startup, heartbeat, provider, or control-plane failure.	Runnable retries once by default; retry manually if it remains terminal.

Manual and repository dispatch

A workflow must declare workflow_dispatch before it can be started manually. Inputs are validated against its immutable input definitions.

manual dispatch requestHTTP

POST /api/workflows/WORKFLOW_ID/dispatch
Content-Type: application/json

{
  "ref": "refs/heads/main",
  "inputs": {
    "environment": "staging",
    "dry-run": false
  }
}

1
Select a workflow
Use the workflow page or list_workflows through MCP to obtain its immutable definition ID.
2
Choose a ref
Pass a branch, tag, full ref, or resolvable commit accepted by the connected source provider.
3
Supply typed inputs
Required, choice, boolean, number, string, and environment values are checked before the run is created.
4
Open the queued run
A successful dispatch returns HTTP 201 with runId and orchestration metadata.

Repository dispatch is separate: send eventType and clientPayload to the repository endpoint. Every active workflow whose repository_dispatch.types matches can create a run.

Cancel and rerun

Members and higher roles can mutate runs in the active organization. Both dashboard and MCP operations enforce the same tenant boundary.

Operation	Behavior
Cancel	Idempotently marks unfinished work cancelled, stops runnable jobs, and cancels durable orchestration. A terminal run remains terminal.
Rerun all	Creates a new run for the same workflow snapshot and source revision, preserving original history.
Rerun failed only	Retries only the failed portion while retaining successful dependency results required to rebuild the DAG safely.
Infrastructure retry	A new attempt is created automatically once by default for infrastructure-only failure; workflow failures and timeouts are not automatically retried.

Prefer failed-only reruns after inspection

Confirm that failure is transient and that successful jobs produced reusable state before retrying. Dispatch a fresh workflow when source, inputs, secrets, or environment configuration changed.

Logs and artifacts

Logs are secret-masked before storage. Retention is frozen from the organization plan when the rows and objects are created.

Output	How to use it
Live job log	Open the job attempt in the run view. Command groups, annotations, summaries, and problem matcher results are rendered structurally.
Download log	Use the download control or `?download=1`. Customer API log responses are `text/plain` and support HTTP byte ranges.
MCP log tail	`get_job_logs` returns a bounded tail: 1–2,000 lines and 1,024–200,000 bytes.
Artifact	List by run, inspect name/size/digest/expiry, then download through the authenticated artifact endpoint.
Expired data	Reads filter expired metadata before object access. Expired logs and artifacts cannot be restored from the customer interface.

Environment approvals and waits

Protection is evaluated before runner assignment or release of environment-scoped secrets.

1
Job enters queued protection
The run page shows the environment, wait timer, branch/tag policy, and pending approval.
2
Eligible reviewer decides
A selected required reviewer approves or rejects with an optional comment. Self-review and admin bypass policies are enforced.
3
Rules converge
The job remains queued until wait time, ref policy, and approval requirements all pass.
4
Runner is assigned
Only then are environment secrets resolved and, unless deployment: false, deployment status history created.

A rejection is terminal for that job

Changing the environment rule does not rewrite the historic decision. Start a new dispatch or rerun after correcting the policy or deployment request.

Common failure states

Use the first non-success admission or execution reason instead of repeatedly pressing rerun.

Symptom	Likely cause	Next check
Queued with no runner	Dependency, concurrency, environment, billing, or plan concurrency gate.	Open the job admission reason and organization usage.
No run after provider event	Trigger filters, invalid/disabled workflow, unselected repository, or duplicate delivery.	Repository diagnostics and provider installation selection.
Checkout fails	Installation access, ref, token permission, Entire URL/token, LFS/submodule credentials, or unsupported SSH/custom host.	Checkout step annotation and provider guide.
Logs stop abruptly	Lost heartbeat, provider exit, timeout, or browser stream interruption.	Refresh the attempt; look for infrastructure_failure and try the downloadable log.
Deployment blocked	Wait, reviewer, self-review, bypass, branch/tag, or subscription rule.	Environment protection details on the queued job.
Dispatch rejected	Missing workflow_dispatch, invalid ref/input, inactive subscription, allowance stop, or hard spend cap.	Workflow diagnostics and Billing controls.

NextMCP setupGive an agent bounded visibility and optional operator controls.