Claude Code GitHub Actions - Quick Reference

Authentication Quick Check

Is everything configured?

# 1. Check GitHub App installation
gh api /repos/cloudnnj/momentum/installation

# 2. Check secrets are configured
gh secret list | grep CLAUDE

# Expected output:
# CLAUDE_CODE_OAUTH_TOKEN  Updated YYYY-MM-DD

Common Authentication Issues

Symptom	Cause	Fix
“GraphQL: Resource not accessible”	Missing permissions in workflow	Add required permission to `permissions:` block
“Command not found: gh”	Tool not allowed	Add `Bash(gh *)` to `claude_args`
“Authentication failed”	Missing/expired token	Re-run `/install-github-app` in Claude CLI
“Operation requires elevated permissions”	User lacks write access	Verify user has write role in repository

Workflow Permission Matrix

Workflow	Contents	Pull Requests	Issues	Actions	Purpose
claude-auto-fix.yml	write	write	write	read	Create PRs and comment
claude-clarification-response.yml	write	write	write	read	Create PRs and comment
claude-code-review.yml	read	read ⚠️	read	-	Read-only review (needs write for commenting!)
claude.yml	read	read	read	read	Interactive Q&A

⚠️ = Permission mismatch detected

Allowed Tools Reference

Secure Pattern (Recommended)

claude_args: |
  --allowed-tools "Bash(gh issue *),Bash(gh pr *),Bash(git *),Bash(npm test),Read,Write,Edit,Glob,Grep,Task"

Current Pattern (Too Permissive)

claude_args: '--allowed-tools "Bash(*),Read,Write,Edit,Glob,Grep,Task"'
# ⚠️ Allows ANY Bash command - security risk!

Read-Only Pattern

# No claude_args = default tools only
# Includes: Read, Edit, Glob, Grep (NO Bash!)

Common Command Patterns

Testing Workflows Locally

# Trigger auto-fix workflow
gh issue edit <issue-number> --add-label "auto-fix"

# Check workflow status
gh run list --workflow=claude-auto-fix.yml --limit 5

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

# Download logs for analysis
gh run download <run-id>

Managing Labels

# Add auto-fix label to trigger workflow
gh issue edit 123 --add-label "auto-fix"

# Check current labels
gh issue view 123 --json labels --jq '.labels[].name'

# Remove label
gh issue edit 123 --remove-label "auto-fix"

Checking Permissions

# View your access level
gh api /repos/cloudnnj/momentum/collaborators/$(gh api /user -q .login)/permission

# Expected output for maintainers:
# {"permission":"admin","role_name":"admin"}

# View workflow permissions
gh workflow view claude-auto-fix.yml --yaml | grep -A 10 "permissions:"

Authentication Flow Diagram

User triggers workflow (issue label, @claude mention, etc.)
    ↓
GitHub Actions workflow starts
    ↓
Action obtains GitHub App token (automatic)
    ↓
Token injected into Claude Code execution environment
    ↓
Claude Code executes with GitHub App permissions
    ↓
Commands respect workflow permissions: block

Token Comparison

Feature	GITHUB_TOKEN	CLAUDE_CODE_OAUTH_TOKEN
Used By	Workflow shell steps	Claude Code execution
Setup	Automatic	Manual (`/install-github-app`)
Lifetime	Duration of workflow	Persistent (until revoked)
Scope	Repository-specific	Repository-specific
Usage	`env: GH_TOKEN: $`	`with: claude_code_oauth_token: $`

Quick Fixes

Fix 1: Enable PR Commenting in Code Review

File: .github/workflows/claude-code-review.yml

# Change this:
permissions:
  pull-requests: read

# To this:
permissions:
  pull-requests: write

Fix 2: Restrict Bash Permissions in Auto-Fix

File: .github/workflows/claude-auto-fix.yml

# Change this:
claude_args: '--allowed-tools "Bash(*),Read,Write,Edit,Glob,Grep,Task"'

# To this:
claude_args: '--allowed-tools "Bash(gh *),Bash(git *),Bash(npm test),Bash(npm run *),Read,Write,Edit,Glob,Grep,Task"'

Fix 3: Add CI/CD Integration (Optional)

Any workflow file:

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read        # ← Add this

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      claude_code_oauth_token: $
      additional_permissions: |
        actions: read   # ← Add this

Security Checklist

All secrets stored in GitHub Secrets (never in workflow files)
claude_args uses specific tool patterns (not Bash(*))
Workflow permissions follow principle of least privilege
User access verification enabled (automatic)
Workflow logs monitored for unexpected behavior
Token rotation schedule established (quarterly minimum)

Monitoring Commands

# View recent workflow failures
gh run list --workflow=claude-auto-fix.yml --status failure --limit 10

# View workflow run details with timing
gh run view <run-id> --log-failed

# Check for authentication errors in logs
gh run view <run-id> --log | grep -i "auth\|permission\|forbidden"

# List all workflow runs for debugging
gh run list --workflow=claude-auto-fix.yml --json number,status,conclusion,createdAt | jq

Emergency Procedures

Revoke Compromised Token

# 1. Delete secret from GitHub
gh secret delete CLAUDE_CODE_OAUTH_TOKEN

# 2. Uninstall GitHub App
# Go to: https://github.com/apps/claude -> Configure -> Uninstall

# 3. Re-install
# Run: claude (in terminal)
# Then: /install-github-app

Temporarily Disable Claude Workflows

# Disable specific workflow
gh workflow disable claude-auto-fix.yml

# Re-enable when ready
gh workflow enable claude-auto-fix.yml

# Or remove auto-fix label from all issues
gh issue list --label "auto-fix" --json number --jq '.[].number' | xargs -I {} gh issue edit {} --remove-label "auto-fix"

Additional Resources

Last Updated: 2025-12-04
Maintainer: DevOps Team