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