GitHub Actions Workflows
Trigger, view, or manage GitHub Actions workflows using gh workflow and gh run.
Arguments
$ARGUMENTS
Format: [action] [args...]
list - List available workflows (default)run <workflow> [--ref <branch>] [inputs...] - Trigger a workflowview [run_id] - View workflow run statuswatch <run_id> - Watch a running workflowlogs <run_id> - View run logs
Examples
/github:workflow-run
/github:workflow-run list
/github:workflow-run run ci.yml
/github:workflow-run run deploy.yml --ref main
/github:workflow-run view
/github:workflow-run view 12345678
/github:workflow-run watch 12345678
/github:workflow-run logs 12345678
Instructions
Required GitHub CLI preflight
Before any workflow step, read ../../references/github-cli-preflight.md and complete it. Do not run workflow commands until gh installation and authentication are verified.
List Workflows (default)
gh workflow list
Show workflow names, states, and IDs.
Trigger Workflow
List available workflows:
gh workflow list
Inspect the workflow and collect inputs:
gh workflow view <workflow>
Collect every required input from the user. Do not guess deployment
environments, release versions, or other sensitive values. Write the input
object as JSON to a temporary file using a JSON-aware tool.
Resolve correlation data: Resolve the selected ref to an exact commit SHA
and record the current UTC timestamp immediately before dispatch.
Require final confirmation: Show the verified repository, workflow,
ref, exact commit SHA, and input names with non-secret values. Redact values
identified as sensitive. Do not trigger until the user explicitly confirms.
Run the workflow non-interactively: If the workflow has inputs, pass the
JSON file. If it has no inputs, omit --json and stdin entirely:
# With inputs
gh workflow run "$workflow" --ref "$workflow_ref" --json < "$inputs_file"
# Without inputs
gh workflow run "$workflow" --ref "$workflow_ref"
Find this dispatch, not merely the latest run: Poll for a
workflow_dispatch run created after the recorded timestamp and matching
the workflow and exact commit SHA. For a branch ref, also filter by branch:
gh run list --workflow "$workflow" \
--event workflow_dispatch \
--branch "$workflow_ref" \
--commit "$expected_head_sha" \
--created ">=$dispatch_started_at" \
--limit 20 \
--json databaseId,createdAt,event,headBranch,headSha,workflowName,url
For a tag or commit ref, omit --branch and verify the returned
headBranch/headSha fields explicitly.
If zero or multiple plausible runs remain, report the ambiguity and ask the
user which run to follow; never silently select --limit 1.
Offer to watch:
gh run watch <run_id>
View Run Status
# Latest run
gh run list --limit 5
# Specific run
gh run view <run_id>
# With web
gh run view <run_id> --web
Watch Running Workflow
gh run watch <run_id>
Shows live status updates until completion.
View Logs
# Full logs
gh run view <run_id> --log
# Failed steps only
gh run view <run_id> --log-failed
Common Workflows
Detect and suggest common workflows:
ci.yml / test.yml - CI/Testingbuild.yml - Builddeploy.yml / release.yml - Deploymentlint.yml - Linting
Error Handling
- If workflow not found: "Error: Workflow '' not found. Available: "
- If workflow disabled: "Error: Workflow is disabled. Enable in repo settings."
- If no permission: "Error: Cannot trigger workflows in this repository"
- If run failed: Show failed steps and suggest viewing logs
1---2name: workflow-run3description: List, inspect, trigger, watch, or rerun GitHub Actions workflows and runs. Use when the user wants to operate or inspect CI workflows, not when they only want to merge a PR or browse the Actions page.4---56# GitHub Actions Workflows78Trigger, view, or manage GitHub Actions workflows using `gh workflow` and `gh run`.910## Arguments1112$ARGUMENTS1314**Format:** `[action] [args...]`1516- `list` - List available workflows (default)17- `run <workflow> [--ref <branch>] [inputs...]` - Trigger a workflow18- `view [run_id]` - View workflow run status19- `watch <run_id>` - Watch a running workflow20- `logs <run_id>` - View run logs2122## Examples2324```25/github:workflow-run26/github:workflow-run list27/github:workflow-run run ci.yml28/github:workflow-run run deploy.yml --ref main29/github:workflow-run view30/github:workflow-run view 1234567831/github:workflow-run watch 1234567832/github:workflow-run logs 1234567833```3435## Instructions3637### Required GitHub CLI preflight3839Before any workflow step, read `../../references/github-cli-preflight.md` and complete it. Do not run workflow commands until `gh` installation and authentication are verified.4041### List Workflows (default)4243```bash44gh workflow list45```4647Show workflow names, states, and IDs.4849### Trigger Workflow50511. **List available workflows:**52 ```bash53 gh workflow list54 ```55562. **Inspect the workflow and collect inputs:**57 ```bash58 gh workflow view <workflow>59 ```60 Collect every required input from the user. Do not guess deployment61 environments, release versions, or other sensitive values. Write the input62 object as JSON to a temporary file using a JSON-aware tool.63643. **Resolve correlation data:** Resolve the selected ref to an exact commit SHA65 and record the current UTC timestamp immediately before dispatch.66674. **Require final confirmation:** Show the verified repository, workflow,68 ref, exact commit SHA, and input names with non-secret values. Redact values69 identified as sensitive. Do not trigger until the user explicitly confirms.70715. **Run the workflow non-interactively:** If the workflow has inputs, pass the72 JSON file. If it has no inputs, omit `--json` and stdin entirely:73 ```bash74 # With inputs75 gh workflow run "$workflow" --ref "$workflow_ref" --json < "$inputs_file"7677 # Without inputs78 gh workflow run "$workflow" --ref "$workflow_ref"79 ```80816. **Find this dispatch, not merely the latest run:** Poll for a82 `workflow_dispatch` run created after the recorded timestamp and matching83 the workflow and exact commit SHA. For a branch ref, also filter by branch:84 ```bash85 gh run list --workflow "$workflow" \86 --event workflow_dispatch \87 --branch "$workflow_ref" \88 --commit "$expected_head_sha" \89 --created ">=$dispatch_started_at" \90 --limit 20 \91 --json databaseId,createdAt,event,headBranch,headSha,workflowName,url92 ```93 For a tag or commit ref, omit `--branch` and verify the returned94 `headBranch`/`headSha` fields explicitly.95 If zero or multiple plausible runs remain, report the ambiguity and ask the96 user which run to follow; never silently select `--limit 1`.97987. **Offer to watch:**99 ```bash100 gh run watch <run_id>101 ```102103### View Run Status104105```bash106# Latest run107gh run list --limit 5108109# Specific run110gh run view <run_id>111112# With web113gh run view <run_id> --web114```115116### Watch Running Workflow117118```bash119gh run watch <run_id>120```121122Shows live status updates until completion.123124### View Logs125126```bash127# Full logs128gh run view <run_id> --log129130# Failed steps only131gh run view <run_id> --log-failed132```133134## Common Workflows135136Detect and suggest common workflows:137- `ci.yml` / `test.yml` - CI/Testing138- `build.yml` - Build139- `deploy.yml` / `release.yml` - Deployment140- `lint.yml` - Linting141142## Error Handling143144- If workflow not found: "Error: Workflow '<name>' not found. Available: <list>"145- If workflow disabled: "Error: Workflow is disabled. Enable in repo settings."146- If no permission: "Error: Cannot trigger workflows in this repository"147- If run failed: Show failed steps and suggest viewing logs
zai-org