workflow-run

name	workflow-run
description	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.

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 workflow
• view [run_id] - View workflow run status
• watch <run_id> - Watch a running workflow
• logs <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

1. List available workflows:

   gh workflow list
   

2. 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.

3. Resolve correlation data: Resolve the selected ref to an exact commit SHA and record the current UTC timestamp immediately before dispatch.

4. 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.

5. 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"
   

6. 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.

7. 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/Testing
• build.yml - Build
• deploy.yml / release.yml - Deployment
• lint.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