Workflows fail on forks without ANTHROPIC_API_KEY — should skip cleanly

[scotthavird]

Problem

The two GitHub Actions workflows shipped with this template — claude.yml (responds to @claude mentions) and claude-review.yml (auto-reviews PRs) — both invoke anthropics/claude-code-action@v1 directly without first checking that the ANTHROPIC_API_KEY secret is configured. When the secret is missing, the action fails with Environment variable validation failed, and the workflow status is failure rather than skipped.

The result: anyone forking this template gets red CI on every PR until they remember to add the secret, with a confusing error message that looks like a real bug. We hit this ourselves on PR #5 (a one-line chore: config change) and on previous PRs. This is a bad first impression for the very thing the template is meant to demonstrate.

Solution

Refactor both workflows into a two-job pattern. A tiny check-secret gate job runs first, exposes a has_key output, and emits a workflow notice when the secret is missing. The downstream responder / review job is gated on needs.check-secret.outputs.has_key == 'true', so when the secret is absent, the downstream job is skipped rather than failed. CI stays green on a fresh fork.

The maintainer is told what to do via a ::notice:: annotation that points them at Settings → Secrets and variables → Actions.

Architecture

flowchart LR
  PR[PR opened] --> CS[check-secret job]
  CS -->|has_key=true| RV[review job runs]
  CS -->|has_key=false| SK[review job skipped<br/>workflow status: success]
  CS -.notice.-> NT[::notice:: 'set ANTHROPIC_API_KEY']
  RV --> CR[Claude posts review]

Loading

Business Impact

• Forks of the template no longer get spurious failed CI checks before configuration.
• Maintainers get a clear actionable notice telling them exactly which secret to add and where.
• Removes a confusing failure mode that looked like a template bug but was an environmental setup issue.

Acceptance Criteria

• claude-review.yml uses the check-secret gate pattern.
• claude.yml uses the check-secret gate pattern (preserving its existing @claude-mention conditional).
• When ANTHROPIC_API_KEY is not set, both workflows complete with the gate job succeeding and the responder/review job skipped, not failed.
• The notice message points the user to Settings → Secrets and variables → Actions.
• docs/integrations.md documents the graceful-skip behavior.
• YAML is valid.

Technical Notes

• Files affected: .github/workflows/claude.yml, .github/workflows/claude-review.yml, docs/integrations.md
• Dependencies: none
• Breaking changes: none. The workflows behave identically when the secret IS set; only the no-secret path changes from fail to skip.

Agent Context

• change-type: fix
• risk-level: low
• test-coverage: YAML validation via python -c "import yaml". End-to-end behavior verified by this very PR running through the updated workflow (it'll be the first PR to test the new gate). If this PR's check-secret job succeeds and the review job is skipped, the fix is confirmed working.
• rollback-plan: git revert the merge commit. Pre-existing behavior was already broken in the same way for any fork that hadn't set the secret, so the rollback returns to the same broken-state baseline.

Workflow Progress

graph LR
    A[Analyze] --> B[Issue] --> C[Branch] --> D[Implement] --> E[PR] --> F[Review] --> G[CI] --> H[Merge] --> I[Deploy] --> J[Shipped]
    classDef done fill:#22c55e,stroke:#16a34a,color:#fff
    classDef active fill:#eab308,stroke:#ca8a04,color:#fff
    classDef todo fill:#d1d5db,stroke:#9ca3af,color:#fff
    class A,B,C,D,E,F,G,H,I,J done

Loading