Workflow Management

GitHub Workflow Management Skill

This skill provides operations for managing GitHub Actions workflows, including viewing runs, triggering workflows, managing artifacts, and monitoring CI/CD pipelines.

Available Operations

1. List Workflow Runs

View workflow run history with filtering options.

2. View Workflow Run Details

Get detailed information about a specific workflow run.

3. Trigger Workflow

Manually trigger a workflow_dispatch workflow.

4. Cancel Workflow Run

Stop a running workflow.

5. Rerun Workflow

Rerun a failed or completed workflow.

6. View Workflow Logs

Download and view logs from workflow runs.

7. Download Artifacts

Download build artifacts from workflow runs.

8. List Workflows

View all workflows in a repository.

9. View Job Details

Get information about individual workflow jobs.

Usage Examples

List Workflow Runs

List all workflow runs:

gh run list --repo owner/repo-name

List runs with limit:

gh run list --repo owner/repo-name --limit 50

Filter by workflow:

gh run list --repo owner/repo-name --workflow "CI"

Filter by branch:

gh run list --repo owner/repo-name --branch main

Filter by status:

gh run list --repo owner/repo-name --status completed
gh run list --repo owner/repo-name --status failure
gh run list --repo owner/repo-name --status in_progress

Filter by event:

gh run list --repo owner/repo-name --event push
gh run list --repo owner/repo-name --event pull_request
gh run list --repo owner/repo-name --event workflow_dispatch

Filter by actor:

gh run list --repo owner/repo-name --user username

JSON output:

gh run list --repo owner/repo-name --json databaseId,headBranch,status,conclusion,workflowName,event

View Workflow Run Details

View run summary:

gh run view 123456 --repo owner/repo-name

View with job details:

gh run view 123456 --repo owner/repo-name --job

View in browser:

gh run view 123456 --repo owner/repo-name --web

View logs:

gh run view 123456 --repo owner/repo-name --log

View failed logs only:

gh run view 123456 --repo owner/repo-name --log-failed

JSON output:

gh run view 123456 --repo owner/repo-name --json status,conclusion,workflowName,headBranch,createdAt,updatedAt

Get run by workflow and branch:

# Get latest run for specific workflow on branch
gh run list --repo owner/repo-name --workflow "CI" --branch main --limit 1

Trigger Workflow

Trigger workflow on default branch:

gh workflow run ci.yml --repo owner/repo-name

Trigger on specific branch:

gh workflow run ci.yml --repo owner/repo-name --ref feature-branch

Trigger with inputs:

gh workflow run deploy.yml --repo owner/repo-name \
  -f environment=production \
  -f version=1.2.3

Trigger and watch:

gh workflow run test.yml --repo owner/repo-name && \
  gh run watch $(gh run list --workflow test.yml --limit 1 --json databaseId --jq '.[0].databaseId')

Using API for complex inputs:

gh api repos/owner/repo-name/actions/workflows/deploy.yml/dispatches \
  -f ref=main \
  -f 'inputs[environment]=staging' \
  -f 'inputs[deploy_type]=full'

Cancel Workflow Run

Cancel specific run:

gh run cancel 123456 --repo owner/repo-name

Cancel all in-progress runs:

gh run list --repo owner/repo-name --status in_progress --json databaseId --jq '.[].databaseId' | \
  xargs -I {} gh run cancel {} --repo owner/repo-name

Cancel runs for specific branch:

gh run list --repo owner/repo-name --branch feature-branch --status in_progress --json databaseId --jq '.[].databaseId' | \
  xargs -I {} gh run cancel {} --repo owner/repo-name

Rerun Workflow

Rerun entire workflow:

gh run rerun 123456 --repo owner/repo-name

Rerun only failed jobs:

gh run rerun 123456 --repo owner/repo-name --failed

Watch rerun:

gh run rerun 123456 --repo owner/repo-name && \
  gh run watch 123456 --repo owner/repo-name

View Workflow Logs

View logs in terminal:

gh run view 123456 --repo owner/repo-name --log

View specific job logs:

gh run view 123456 --repo owner/repo-name --job 987654 --log

Download logs:

gh run download 123456 --repo owner/repo-name --name logs

Stream live logs:

gh run watch 123456 --repo owner/repo-name

Download all logs as zip:

gh api repos/owner/repo-name/actions/runs/123456/logs > logs.zip

Download Artifacts

List artifacts for a run:

gh run view 123456 --repo owner/repo-name --json artifacts

Download all artifacts:

gh run download 123456 --repo owner/repo-name

Download specific artifact:

gh run download 123456 --repo owner/repo-name --name artifact-name

Download to specific directory:

gh run download 123456 --repo owner/repo-name --dir ./downloads

Using API to download:

# List artifacts
gh api repos/owner/repo-name/actions/runs/123456/artifacts --jq '.artifacts[] | {name, id, size_in_bytes}'

# Download specific artifact
ARTIFACT_ID=$(gh api repos/owner/repo-name/actions/runs/123456/artifacts --jq '.artifacts[0].id')
gh api repos/owner/repo-name/actions/artifacts/$ARTIFACT_ID/zip > artifact.zip

List Workflows

List all workflows:

gh workflow list --repo owner/repo-name

View workflow details:

gh workflow view ci.yml --repo owner/repo-name

View in browser:

gh workflow view ci.yml --repo owner/repo-name --web

Enable/disable workflow:

gh workflow enable ci.yml --repo owner/repo-name
gh workflow disable ci.yml --repo owner/repo-name

Get workflow state:

gh api repos/owner/repo-name/actions/workflows/ci.yml --jq '{state, path, name}'

View Job Details

List jobs in a run:

gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | {name, status, conclusion}'

View specific job:

gh api repos/owner/repo-name/actions/jobs/987654 --jq '{name, status, conclusion, started_at, completed_at, steps}'

View job logs:

gh api repos/owner/repo-name/actions/jobs/987654/logs

Rerun specific job:

gh api repos/owner/repo-name/actions/jobs/987654/rerun -X POST

Common Patterns

Monitor CI/CD Pipeline

# 1. Trigger workflow
gh workflow run ci.yml --repo owner/repo-name --ref main

# 2. Wait a moment for run to start
sleep 5

# 3. Get the run ID
RUN_ID=$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# 4. Watch the run
gh run watch $RUN_ID --repo owner/repo-name

# 5. Check result
gh run view $RUN_ID --repo owner/repo-name --json conclusion --jq '.conclusion'

# 6. Download artifacts if successful
if [ "$(gh run view $RUN_ID --json conclusion --jq -r '.conclusion')" = "success" ]; then
  gh run download $RUN_ID --repo owner/repo-name
fi

Debug Failed Workflow

# 1. List recent failures
gh run list --repo owner/repo-name --status failure --limit 5

# 2. View failed run
gh run view 123456 --repo owner/repo-name --log-failed

# 3. Check job details
gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, steps: [.steps[] | select(.conclusion=="failure") | {name, conclusion}]}'

# 4. Download logs for analysis
gh api repos/owner/repo-name/actions/runs/123456/logs > debug-logs.zip

# 5. Rerun failed jobs after fix
gh run rerun 123456 --repo owner/repo-name --failed

Deployment Workflow

# 1. Trigger deployment
gh workflow run deploy.yml --repo owner/repo-name \
  --ref main \
  -f environment=production \
  -f version=$(cat VERSION)

# 2. Monitor deployment
RUN_ID=$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID --repo owner/repo-name

# 3. Verify success
if [ "$(gh run view $RUN_ID --json conclusion --jq -r '.conclusion')" = "success" ]; then
  echo "Deployment successful!"
  gh run view $RUN_ID --repo owner/repo-name
else
  echo "Deployment failed!"
  gh run view $RUN_ID --repo owner/repo-name --log-failed
  exit 1
fi

Cleanup Old Workflow Runs

# List old completed runs
gh run list --repo owner/repo-name --status completed --limit 100 --json databaseId,createdAt

# Delete runs older than 30 days (using API)
CUTOFF_DATE=$(date -d '30 days ago' -Iseconds)
gh api repos/owner/repo-name/actions/runs --paginate --jq ".workflow_runs[] | select(.created_at < \"$CUTOFF_DATE\") | .id" | \
  xargs -I {} gh api repos/owner/repo-name/actions/runs/{} -X DELETE

Bulk Rerun Failed Workflows

# Get all failed runs from last week
gh run list --repo owner/repo-name --status failure --created ">=$(date -d '7 days ago' +%Y-%m-%d)" --json databaseId --jq '.[].databaseId' | \
  while read run_id; do
    echo "Rerunning $run_id"
    gh run rerun $run_id --repo owner/repo-name
    sleep 2  # Rate limiting
  done

Check Workflow Coverage

# List all workflows and their recent status
gh workflow list --repo owner/repo-name --json name,path,state | \
  jq -r '.[] | "\(.name) (\(.path)): \(.state)"'

# Check each workflow's latest run
gh workflow list --repo owner/repo-name --json name,path | \
  jq -r '.[].path' | \
  while read workflow; do
    echo "Workflow: $workflow"
    gh run list --workflow "$workflow" --limit 1 --repo owner/repo-name
    echo ""
  done

Advanced Usage

Matrix Job Analysis

View all matrix jobs:

gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | {name, status, conclusion, matrix: .steps[0].name}'

Find failed matrix combinations:

gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, conclusion}'

Workflow Timing Analysis

Get workflow duration:

gh run view 123456 --repo owner/repo-name --json createdAt,updatedAt --jq '{created: .createdAt, updated: .updatedAt}'

Analyze job timing:

gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | {name, duration: (.completed_at - .started_at)}'

Concurrent Workflow Management

List concurrent runs:

gh run list --repo owner/repo-name --status in_progress

Cancel concurrent runs for same branch:

BRANCH="feature-branch"
gh run list --repo owner/repo-name --branch $BRANCH --status in_progress --json databaseId --jq '.[1:] | .[].databaseId' | \
  xargs -I {} gh run cancel {} --repo owner/repo-name

Self-Hosted Runner Management

View runner groups:

gh api repos/owner/repo-name/actions/runners --jq '.runners[] | {name, status, busy}'

Check runner usage:

gh api repos/owner/repo-name/actions/runs/123456/jobs --jq '.jobs[] | {name, runner_name: .runner_name, runner_group_name: .runner_group_name}'

Error Handling

Workflow Not Found

# List available workflows
gh workflow list --repo owner/repo-name

# Verify workflow file exists
gh api repos/owner/repo-name/contents/.github/workflows --jq '.[].name'

Run Not Found

# Verify run exists
gh run view 123456 --repo owner/repo-name 2>&1 | grep -q "could not find" && echo "Run not found"

Workflow Dispatch Not Available

# Check if workflow has workflow_dispatch trigger
gh api repos/owner/repo-name/actions/workflows/ci.yml --jq '.workflow_dispatch'

Rate Limiting

# Check rate limit
gh api rate_limit --jq '.resources.actions'

# Use pagination for large results
gh api repos/owner/repo-name/actions/runs --paginate

Best Practices

1. Monitor actively: Use gh run watch for important workflows
2. Clean up old runs: Regularly delete old workflow runs to save storage
3. Use meaningful names: Name workflows clearly for easy identification
4. Handle failures gracefully: Set up notifications for failed workflows
5. Download artifacts promptly: Artifacts have retention limits
6. Use workflow_dispatch: Enable manual triggers for debugging
7. Check logs first: Review logs before rerunning failed workflows
8. Respect rate limits: Add delays when bulk processing runs
9. Use JSON output: For programmatic processing and scripting
10. Tag deployments: Use releases or tags to track deployment workflows

Workflow Status Values

Status:

• queued - Waiting to start
• in_progress - Currently running
• completed - Finished (check conclusion for result)

Conclusion:

• success - Completed successfully
• failure - Failed
• cancelled - Manually cancelled
• skipped - Skipped
• timed_out - Exceeded time limit
• action_required - Needs manual approval
• neutral - Completed but not success/failure

Integration with Other Skills

• Use pull-request-management to view PR check status
• Use commit-operations to find commits that triggered workflows
• Use issue-management to link workflow failures to issues
• Use repository-management to manage workflow files

References

• GitHub CLI Run Documentation
• GitHub Actions Documentation
• Workflow Syntax
• GitHub Actions API