GitHub Actions Debug Skill

This skill helps investigate and debug GitHub Actions workflow failures using the GitHub CLI (gh).

When to Use

• GitHub Actions workflows are failing
• Need to understand why CI/CD is not working
• Investigating test failures in CI
• Analyzing build or deployment issues
• Checking workflow run history

Task

Systematically investigate GitHub Actions issues using the following workflow:

1. List Recent Workflow Runs

Start by getting an overview of recent runs:

# List last 10 workflow runs
gh run list --limit 10

# List runs for a specific workflow
gh run list --workflow=test.yml --limit 10

# List only failed runs
gh run list --status=failure --limit 10

# List runs on a specific branch
gh run list --branch=main --limit 10

2. View Run Summary

Get detailed information about a specific run:

# View run summary by ID
gh run view <RUN_ID>

# View the most recent run for a workflow
gh run view --workflow=test.yml

The summary includes:

• Overall status (success, failure, cancelled)
• Jobs and their status
• Annotations and errors
• Trigger event and branch

3. View Failed Job Logs

Get detailed logs from failed jobs:

# View logs of failed steps only
gh run view <RUN_ID> --log-failed

# View all logs for a run
gh run view <RUN_ID> --log

# View logs for a specific job
gh run view <RUN_ID> --job=<JOB_ID> --log

4. Common Failure Patterns to Look For

When analyzing logs, look for:

Configuration Errors

• Invalid YAML syntax
• Unknown workflow triggers
• Invalid action versions
• Missing or invalid parameters

Example:

jsonschema: "output" does not validate
additional properties 'format' not allowed

→ Check for deprecated or invalid configuration options

Dependency Issues

• Package installation failures
• Version mismatches
• Cache restoration failures
• Missing dependencies

Example:

Failed to restore: "/usr/bin/tar" failed with error

→ Cache corruption; may need to clear cache or update cache keys

Test Failures

• Unit test failures
• Integration test timeouts
• Race conditions
• Environment-specific issues

Build Errors

• Compilation errors
• Linter failures
• Type errors
• Import errors

Permission Issues

• Authentication failures
• Missing secrets
• Insufficient permissions
• Token expiration

5. Investigation Checklist

• Identify the failing workflow and job
• Check the trigger event (push, PR, schedule)
• Review the error messages and annotations
• Compare with successful runs to identify changes
• Check for configuration file changes
• Verify dependency versions
• Look for environment-specific issues
• Check secrets and permissions

6. Common Fixes

Update Workflow Triggers

Add or modify trigger events:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Fix Configuration Errors

Remove deprecated options or update to new syntax:

# Old (may not work with new versions)
output:
  format: colored-line-number
  print-issued-lines: true

# Fixed (remove unsupported options)
# (many tools use their own config or defaults)

Clear or Update Cache

Add cache versioning:

- uses: actions/cache@v4
  with:
    path: ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}-v2  # Increment version

Update Action Versions

Use specific versions instead of @master:

# Before
- uses: some-action@master

# After
- uses: some-action@v3

Fix Permissions

Add required permissions:

permissions:
  contents: read
  pull-requests: write
  checks: write  # Add if needed

Output Format

Provide a structured analysis:

1. Issue Summary: Brief description of the failure
2. Root Cause: What caused the failure
3. Affected Workflows: Which workflows/jobs are impacted
4. Fix Applied: What changes were made
5. Verification: How to verify the fix works

For each issue found, include:

• Location: Workflow file and line number
• Error Message: Exact error from logs
• Explanation: Why this error occurred
• Solution: How to fix it
• Prevention: How to avoid similar issues

Useful Commands Reference

# List all workflows
gh workflow list

# View workflow definition
gh workflow view <WORKFLOW_NAME>

# Manually trigger a workflow
gh workflow run <WORKFLOW_NAME>

# Watch a running workflow
gh run watch <RUN_ID>

# Download artifacts from a run
gh run download <RUN_ID>

# Re-run a failed workflow
gh run rerun <RUN_ID>

# Re-run only failed jobs
gh run rerun <RUN_ID> --failed

# Cancel a running workflow
gh run cancel <RUN_ID>

# Delete a workflow run
gh run delete <RUN_ID>

Tips

1. Start broad, then narrow: List runs → View summary → Check failed logs
2. Compare with successful runs: Look for what changed
3. Check recent commits: Workflow file changes often cause issues
4. Verify locally first: Run tests locally before pushing fixes
5. Use workflow dispatch: Test workflow changes with manual triggers
6. Check GitHub Status: Sometimes issues are platform-wide
7. Review action versions: Breaking changes in actions can cause failures

Example Investigation Workflow

# 1. Check recent failures
gh run list --status=failure --limit 5

# 2. Get details on the latest failure
gh run view <RUN_ID>

# 3. View only failed job logs
gh run view <RUN_ID> --log-failed

# 4. Identify the issue (e.g., config error in .golangci.yml)

# 5. Fix the issue locally

# 6. Verify the fix
go run github.com/golangci/golangci-lint/cmd/golangci-lint@latest config verify

# 7. Commit and push

# 8. Monitor the new run
gh run watch