GitHub Actions Workflow Runs

Setup

1. Add a GitHub fine-grained token as a VX Agents Bearer credential, with repository permission Actions (read and write) on the repositories you want covered.
2. Every call pins X-GitHub-Api-Version: 2022-11-28.
3. Worth pinning: owner and repo when the agent works on one repository.

Triage a failing build

1. listWorkflowRuns with status=failure (or branch, event, head_sha, created=>=2026-10-01) to find the run; listRunsForWorkflow narrows to one workflow (id or file name such as ci.yml, from listWorkflows).
2. getWorkflowRun for status, conclusion, head_branch, head_sha and run_attempt.
3. listJobsForRun (filter=latest) shows each job and its steps with conclusion; pick the failed job. getJob gives one job in detail.
4. downloadJobLogs returns a short-lived link (HTTP 302 Location) to the plain-text log; read the lines around the failed step.
5. listRunArtifacts lists test reports or builds the run uploaded (archive_download_url).
6. To retry, tell the user what will run and confirm, then rerunFailedJobs (only failed jobs and their dependents) or rerunWorkflow (all jobs). Add {"enable_debug_logging": true} for more detail.
7. To stop a stuck run, confirm, then cancelWorkflowRun.

Start a workflow by hand

1. getWorkflow to check it exists and is active; the workflow file must have a workflow_dispatch trigger.
2. Confirm branch and inputs with the user, then dispatchWorkflow with {"ref": "main", "inputs": {"environment": "staging"}}. Only send inputs the workflow defines (at most 25).
3. listRunsForWorkflow with event=workflow_dispatch to follow the new run.

Good to know

• Run status values: queued, in_progress, completed; when completed, conclusion is success, failure, cancelled, skipped or timed_out.
• Lists page with per_page (max 100) and page; run lists return at most 1,000 results per query, so filter by created.
• Log links expire after about a minute; fetch them right away.
• Re-runs, cancels and dispatches use CI minutes and can deploy code: always confirm first. Disabling workflows and deleting runs or logs are not part of this spec.

Source: GitHub REST API reference for Actions workflows, workflow runs, jobs and artifacts (https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28), checked 2026-10-20.