GitHub Actions Troubleshooting Skill

This skill helps analyze and troubleshoot GitHub Actions workflows in the current repository.

When to Use This Skill

• User asks about CI/CD failures or build errors
• User mentions "GitHub Actions", "workflow", "pipeline", or "CI logs"
• User wants to see status of recent workflow runs
• User needs to troubleshoot a failed commit or pull request
• User asks about a specific workflow run

Prerequisites

Check for gh CLI availability:

which gh

If gh is not available, inform the user that the GitHub CLI (gh) is required and provide installation instructions for their platform.

Authentication and Access

Before proceeding, verify that gh is authenticated with the correct account that has access to the repository:

# Check current authentication status
gh auth status

# Verify which account is active
gh api user --jq '.login'

IMPORTANT: If the repository is in an organization (e.g., organization/repo), ensure the authenticated account has access to that organization.

Interactive Account Switching

The check_gh_cli() function automatically validates repo access and, when running in an interactive terminal:

• Detects if current account lacks access to the repository
• Lists all available authenticated accounts
• Prompts you to select and switch to the correct account
• Verifies the selected account has access
• Automatically proceeds if access is granted

Example interactive session:

Current account 'personal-user' cannot access 'company/private-repo'

Available accounts:
 1. personal-user
 2. work-user

Select an account to switch to (1-2, or 'n' to skip): 2
Switching to account: work-user
Successfully switched to work-user
✓ Account work-user has access to company/private-repo

In non-interactive environments (scripts, CI/CD), the function will display an error message with manual instructions instead of prompting.

Common authentication issues:

• Wrong account: Authenticated with personal account but repo is in organization
• Multiple accounts: Need to switch to the right one using gh auth switch
• Missing permissions: Account lacks access to private repo or organization

Step 1: Detect GitHub Repository

Check if the current directory is a GitHub repository:

git remote get-url origin 2>/dev/null | grep -q github.com

If this fails or returns non-GitHub URL, inform user this is not a GitHub repository.

Extract owner and repo name:

git remote get-url origin | sed -E 's#.*github\.com[:/]([^/]+)/([^.]+)(\.git)?#\1/\2#'

Step 2: Check if GitHub Actions is Enabled

Two methods to verify Actions is configured:

Method 1: Check for workflow files

ls -la .github/workflows/

Method 2: Query GitHub API

gh api repos/:owner/:repo/actions/workflows --jq '.total_count'

If no workflows exist, inform user that GitHub Actions is not configured for this repository.

Step 3: Finding Workflow Runs

By Commit SHA

When user mentions a specific commit or references HEAD:

# Get commit SHA if needed
COMMIT_SHA=$(git rev-parse HEAD)

# Find runs for that commit
gh run list --commit $COMMIT_SHA --json databaseId,status,conclusion,workflowName,headBranch,createdAt --limit 10

By Branch

gh run list --branch <branch-name> --json databaseId,status,conclusion,workflowName,createdAt --limit 10

Recent Failures

gh run list --status failure --json databaseId,status,conclusion,workflowName,headBranch,createdAt --limit 5

All Recent Runs

gh run list --limit 20 --json databaseId,status,conclusion,workflowName,headBranch,createdAt

Step 4: Viewing Workflow Run Details

Summary View

gh run view <run-id> --verbose

This shows:

• Workflow name and status
• Triggered by and event
• All jobs with their status
• Job steps when using --verbose

Check Status Only

gh run view <run-id> --json status,conclusion,workflowName,headBranch --jq '.'

Step 5: Analyzing Logs

Failed Steps Only (Recommended First)

gh run view <run-id> --log-failed

This shows only the logs for steps that failed, making it easier to identify issues.

Full Logs

gh run view <run-id> --log

Specific Job Logs

# First, list jobs to get job ID
gh run view <run-id> --json jobs --jq '.jobs[] | {id: .databaseId, name: .name, status: .status, conclusion: .conclusion}'

# Then view specific job
gh run view <run-id> --job <job-id> --log

Step 6: Common Troubleshooting Patterns

Pattern: Recent push failed

# Get the last commit SHA
COMMIT_SHA=$(git rev-parse HEAD)

# Find runs for that commit
RUNS=$(gh run list --commit $COMMIT_SHA --json databaseId,status,conclusion,workflowName)

# If any failed, get the run ID and show failed logs
RUN_ID=$(echo "$RUNS" | jq -r 'first(.[] | select(.conclusion == "failure")) | .databaseId')

if [ -n "$RUN_ID" ]; then
  echo "Found failed run: $RUN_ID"
  gh run view $RUN_ID --log-failed
fi

Pattern: Check CI status before merging

# Get current branch
BRANCH=$(git branch --show-current)

# Show recent runs on this branch
gh run list --branch $BRANCH --limit 5 --json databaseId,status,conclusion,workflowName,createdAt

Pattern: Compare with successful runs

# Find last successful run of a workflow
gh run list --workflow <workflow-name> --status success --limit 1 --json databaseId,headSha

# Find failed runs
gh run list --workflow <workflow-name> --status failure --limit 5 --json databaseId,headSha,createdAt

Helper Script

Use the helper script in scripts/gh_actions_helper.sh for common operations:

source "$(dirname "$0")/scripts/gh_actions_helper.sh"

# Check if in GitHub repo with Actions
check_github_actions_repo

# Get latest run for current commit
get_latest_run_for_commit "$(git rev-parse HEAD)"

# Analyze common failure patterns in logs
analyze_failure_logs "$RUN_ID"

Error Handling

gh not authenticated

gh auth status

If not authenticated:

gh auth login

Wrong account or insufficient access

If you see errors like HTTP 404: Not Found when accessing organization repositories:

# Check which account is currently active
gh auth status
gh api user --jq '.login'

# List all authenticated accounts
gh auth status --show-token=false

# Switch to a different account
gh auth switch

# Or login with the correct account
gh auth login

The check_gh_cli() helper function will detect this automatically and provide specific guidance about which account you're using and what's needed.

Rate limiting

GitHub API has rate limits. Check status:

gh api rate_limit

Private repositories

Ensure gh has appropriate permissions:

gh auth refresh -s read:org,repo

Output to User

Always provide:

1. Context: What workflow/job failed
2. Status: Current state (failed, in_progress, etc.)
3. Key errors: Extract relevant error messages from logs
4. Actionable next steps: What to fix or investigate

Example response format:

Workflow "CI" failed on commit abc123 (5 minutes ago)

Failed job: "test"
Failed step: "Run tests"

Error found:
  ERROR: Test suite failed
  FAILED tests/test_api.py::test_endpoint - AssertionError

Next steps:
- Run `pytest tests/test_api.py::test_endpoint` locally
- Check recent changes to test_api.py or endpoint logic