claude-code-github-workflows

# Claude Code GitHub Workflows ## When to Use This Skill | Use this skill when... | Use the linked sibling instead when... | |---|---| | Designing a new `anthropics/claude-code-action@v1` workflow (PR review, issue triage, CI auto-fix) | Configuring the auth method or hardening permissions — see github-actions-auth-security | | Choosing trigger events (`issue_comment`, `pull_request`, `workflow_run`) and `if:` guards | Wiring MCP servers and `--allowedTools` patterns — see github-actions-mcp-config | | Adding path filters, custom trigger phrases, or external-contributor flows | Debugging a failing workflow run — see github-actions-inspection | | Authoring the `prompt:` block (review focus areas, triage labelling, auto-fix instructions) | Building a self-hosted reusable auto-fix workflow — see github-workflow-auto-fix `--reusable` | Expert knowledge for designing GitHub Actions workflows that integrate Claude Code for automated code assistance, PR reviews, and issue triage. ## Core Expertise **Workflow Design Patterns** - Automated pull request reviews with inline comments - Issue triage and automated responses - CI failure auto-fix workflows - Custom trigger configurations and event handling **Trigger Configurations** - Issue comment triggers (`@claude` mentions) - Pull request events (opened, synchronize, ready_for_review) - Workflow run triggers (CI failure handling) - Path-filtered reviews for specific directories ## Display name convention Every workflow's `name:` follows `<Domain>: <Action> [<target>]` (quoted, since YAML treats `:` as a key separator). Use the `Claude:` domain for Claude Code-driven workflows; use `Auto-fix:` for `workflow_run`-triggered remediation. See `.claude/rules/workflow-naming.md` for the canonical rule and active domains. The example snippets below dogfood the convention. When a workflow's `on.workflow_run.workflows` lists another workflow's display name, the listed string must match the target workflow's `name:` exactly — update both sides in the same change. ## Essential Workflow Template ```yaml name: "Claude: @mentions" on: issue_comment: types: [created] pull_request_review_comment: types: [created] issues: types: [opened, assigned] jobs: claude: if: | (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write actions: read steps: - name: Checkout repository uses: actions/checkout@v5 with: fetch-depth: 1 - name: Run Claude Code uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --model opus --effort medium ``` ## Automation Patterns When you need a complete template beyond the essential one above, open [references/automation-patterns.md](references/automation-patterns.md): comprehensive PR review, CI failure auto-fix (`workflow_run`), issue triage and labeling, path-filtered review, custom trigger phrase, and external-contributor handling. Read the `pull_request_target` security caveat there before using the external-contributor template. ## claude-code-action v1 Gotchas Hard-won facts that produce silently-broken workflows (each cost real debugging in production; see laurigates/.github#17–#19): ### Outputs are fixed — counts need `--json-schema` The action exposes **only** `execution_file`, `branch_name`, `github_token`, `structured_output`, and `session_id`. Referencing anything else (`steps.scan.outputs.total`) evaluates to empty with no error — and prompting Claude to print `TOTAL: <n>` in a comment does **not** create a step output. Any metric a workflow needs out of a Claude step goes through structured output: ```yaml - id: scan uses: anthropics/claude-code-action@v1 with: claude_args: >- --json-schema '{"type":"object","properties":{"total_issues":{"type":"integer"}},"required":["total_issues"]}' prompt: | ...analysis instructions... Report the count in the structured output field total_issues. # Read it back — the || '{}' guard is REQUIRED: job outputs evaluate even # when the step was skipped, and fromJSON('') errors. outputs: issues: ${{ fromJSON(steps.scan.outputs.structured_output || '{}').total_issues }} ``` The same guarded expression works in `if:` gates (`fromJSON(... || '{}').critical > 0`) — an unguarded comparison against a missing output silently never fires. The same law covers comment markers: anything CI greps for in an agent's output must be written by a workflow step, not requested from the model — see [REFERENCE.md](REFERENCE.md) § A marker the model has to emit. ### Bots are blocked by default `allowed_bots` defaults to empty — **no** bot may trigger the action, so bot-authored PRs (Renovate, release-please, Dependabot) fail with "Workflow initiated by non-human actor". Pass `allowed_bots: "renovate[bot]"` (or a comma-separated list) on workflows where bot PRs are the point, e.g. dependency audits triggered by lockfile changes. Re-running a failed run does not help: the replay keeps the original bot `sender`. A PR a workflow pushed to with `github.token` meets the same refusal (`allowed_bots: "github-actions"` admits it). That case, a changed workflow dispatched from a branch that skips the agent yet reports success, and denials reported only as a count are detailed in [REFERENCE.md](REFERENCE.md) § More claude-code-action v1 gotchas. ### Deprecated inputs (removed in a future version) `direct_prompt`, `override_prompt`, `custom_instructions`, `max_turns`, `model`, `fallback_model`, `allowed_tools`, `disallowed_tools`, `mcp_config`, `claude_env`, `mode` are all deprecated. Use `prompt` plus `claude_args` (`--model`, `--max-turns`, `--allowedTools`, `--disallowedTools`, `--mcp-config`, `--system-prompt`) and `settings` (env). A deprecated input may be silently ignored — a workflow using `direct_prompt` can run with no prompt at all. ### Budget levers `claude_args` supports `--max-turns` (turn count) and `--max-budget-usd` (run-level spend cap); there is **no token-count budget**. Both fail the run mid-flight when exhausted — they bound waste but don't prevent doomed runs on oversized diffs; pre-gate on diff size for that. Turn-budget exhaustion is recognizable by `error_max_turns` in the `execution_file` and by a *rotating* set of failing AI jobs across re-runs of the same commit. `--model` and `--effort` are the cost levers, not `--max-turns`. `--model` takes an alias (`opus`, `sonnet`, `fable`, `best`) or a full id; aliases move with each model generation, so record the alias you chose next to the effort. `--effort low|medium|high|xhigh|max` overrides the harness default (`high`); effort names do not map across model generations, so re-check the level when the alias's target changes. `haiku` supports no `--effort` at all, so `opus --effort low` is the cheap tier, not haiku. Every template — the Essential Workflow Template and those in [references/automation-patterns.md](references/automation-patterns.md) — carries both, with effort picked by job shape, e.g. ```yaml claude_args: | --model opus --effort medium ``` ## Performance Optimization ### Checkout Optimization ```yaml # Fast checkout for large repos - uses: actions/checkout@v5 with: fetch-depth: 1 # Shallow clone sparse-checkout: | # Only needed paths .github src tests ``` ### Conversation Limits ```yaml # Control execution time and cost claude_args: | --max-turns 10 # Limit back-and-forth exchanges ``` ### Conditional Execution ```yaml # Skip unnecessary runs jobs: claude: if: | contains(github.event.comment.body, '@claude') && !contains(github.event.comment.body, 'ignore') ``` ## Repository Configuration ### CLAUDE.md Create `CLAUDE.md` in repository root to define coding standards; a starter covering code standards, workflow, commit messages, testing and security is in [REFERENCE.md](REFERENCE.md) § A starter CLAUDE.md. ## Quick Setup 1. **Install Claude GitHub App**: https://github.com/apps/claude 2. **Add API Key**: Repository Settings → Secrets → `ANTHROPIC_API_KEY` 3. **Create Workflow**: `.github/workflows/claude.yml` (use template above) 4. **Test**: Create issue and comment `@claude Hello!` 5. **(Optional)** Add `CLAUDE.md` in repo root for project standards ## Troubleshooting ### Workflow Not Triggering - Check trigger conditions in `if:` clause - Verify permissions (contents, pull-requests, issues) - Check GitHub App installation ### Permission Denied - Ensure proper permissions in workflow - Check branch protection rules - Verify repository access For advanced configuration including MCP servers, tool permissions, and authentication methods, see the github-actions-mcp-config and github-actions-auth-security skills. For the secure-use baseline these templates follow (least-privilege permissions, script-injection indirection, `pull_request_target` hazards), see `.claude/rules/github-actions-security.md`.