name: workflow
description: Manage GitHub Actions workflows using gh CLI. Use to check CI status, view run logs, analyze failures, and rerun workflows.

GitHub Actions Workflow Manager

Monitor and manage CI/CD workflows using the GitHub CLI.

Prerequisites

Install GitHub CLI:

brew install gh
# or
curl -sS https://webi.sh/gh | sh

Authenticate:

gh auth login

CLI Reference

Quick Status Check

# Current branch CI status
gh run list --branch $(git branch --show-current) --limit 5

# All recent runs
gh run list --limit 10

# Filter by workflow
gh run list --workflow "CI" --limit 5

View Specific Run

# Get run details
gh run view <run-id>

# View with logs
gh run view <run-id> --log

# Failed jobs only
gh run view <run-id> --log-failed

# Exit codes for CI scripts
gh run view <run-id> --exit-status

List Runs with Filters

# By branch
gh run list --branch main --limit 10

# By workflow name
gh run list --workflow "Build and Test" --limit 10

# By status
gh run list --status failure --limit 10
gh run list --status success --limit 10
gh run list --status in_progress --limit 10

# Combined filters
gh run list --branch main --workflow "CI" --status failure --limit 5

Rerun Workflows

# Rerun entire workflow
gh run rerun <run-id>

# Rerun only failed jobs
gh run rerun <run-id> --failed

# Rerun specific job
gh run rerun <run-id> --job <job-id>

Watch Running Workflow

# Watch a run in progress
gh run watch <run-id>

# Watch and exit with run's exit code
gh run watch <run-id> --exit-status

Download Artifacts

# List artifacts from a run
gh run view <run-id> --json artifacts

# Download all artifacts
gh run download <run-id>

# Download specific artifact
gh run download <run-id> --name "artifact-name"

# Download to specific directory
gh run download <run-id> --dir ./artifacts

Cancel a Run

gh run cancel <run-id>

View Workflow Files

# List workflow files
gh workflow list

# View specific workflow
gh workflow view "CI"

# Enable/disable workflow
gh workflow enable "CI"
gh workflow disable "CI"

Run Workflow Manually

# Trigger workflow_dispatch
gh workflow run "CI"

# With inputs
gh workflow run "Deploy" -f environment=staging -f version=1.2.3

# On specific branch
gh workflow run "CI" --ref feature-branch

Output Formats

# JSON output for parsing
gh run list --json status,conclusion,name,headBranch,url

# Specific fields
gh run view <run-id> --json jobs,status,conclusion

Workflow Patterns

Quick CI Check

# Is my branch passing?
gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion

Debug Failing CI

# 1. Find the failing run
gh run list --branch main --status failure --limit 1

# 2. View failed logs
gh run view <run-id> --log-failed

# 3. After fixing, rerun
gh run rerun <run-id> --failed

Monitor Deployment

# Watch deployment in progress
gh run watch <run-id>

# Get notified when done (macOS)
gh run watch <run-id> && osascript -e 'display notification "Deployment complete"'

Retry Flaky Tests

# Rerun just the failed jobs
gh run rerun <run-id> --failed

Pre-Merge Check

# Ensure all checks pass before merging
gh run list --branch $(git branch --show-current) --json conclusion --jq '.[0].conclusion'

Common Statuses

Best Practices

1. Check status before merge - Ensure CI passes
2. Use --log-failed - Only see relevant failure logs
3. Rerun --failed first - Faster than full rerun
4. Watch long runs - Don't poll manually
5. Download artifacts - For test reports, coverage, etc.
6. Use JSON output - For scripting and parsing