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 listInspect 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
--jsonand 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_dispatchrun 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,urlFor a tag or commit ref, omit
--branchand verify the returnedheadBranch/headShafields 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