fix(workflows): add security and parameterization to Claude workflows

[simonheimlicher]

Overview

Addresses security vulnerability and adds comprehensive parameterization to Claude Code GitHub workflows.

Fixes: #1 (comment)

Security Fix (Critical) 🔒

The original workflows had a critical vulnerability where any external user could trigger Claude workflows that use CLAUDE_CODE_OAUTH_TOKEN. This PR adds authorization checks to restrict workflow execution to trusted contributors only.

Changes:

• ✅ Add author_association verification to all workflow triggers
• ✅ Only OWNER, MEMBER, and COLLABORATOR roles can trigger workflows
• ✅ Add concurrency controls to prevent workflow spam

Before: Any external commenter could trigger workflows → token exposure risk
After: Only trusted contributors can trigger workflows → token protected

Parameterization 🎛️

Extract repeated configuration values into GitHub Actions variables, enabling runtime configuration without code changes.

Configuration Variables Added:

Claude Assistant (claude.yml):

• CLAUDE_AUTHORIZED_ROLES - Control who can trigger (default: ["OWNER", "MEMBER", "COLLABORATOR"])
• CLAUDE_MENTION_TRIGGER - Customize trigger word (default: @claude)
• CLAUDE_CONCURRENCY_CANCEL - Enable canceling in-progress runs (default: false)
• CLAUDE_ALLOWED_TOOLS - Restrict tool access (default: unrestricted)
• CLAUDE_CUSTOM_PROMPT - Override default behavior (default: empty)

Code Review (claude-code-review.yml):

• CLAUDE_REVIEW_AUTHORIZED_ROLES - Who can trigger reviews
• CLAUDE_REVIEW_CONCURRENCY_CANCEL - Cancel in-progress reviews
• CLAUDE_REVIEW_ALLOWED_TOOLS - Tool restrictions (default: gh commands only)
• CLAUDE_REVIEW_CUSTOM_PROMPT - Custom review instructions

Benefits:

• 🎯 DRY: Authorization roles defined once (was repeated 5 times)
• ⚙️ Flexible: Change behavior via repo settings without editing code
• 🔒 Secure: Easily adjust who can trigger workflows
• 📝 Documented: Comprehensive guide in .github/CLAUDE_WORKFLOWS.md

Documentation 📚

Added .github/CLAUDE_WORKFLOWS.md with:

• Detailed description of all configuration variables
• Security best practices
• 5 real-world configuration examples
• Step-by-step guides for setting variables
• Troubleshooting section

Testing

• ✅ YAML syntax validated with yamllint
• ✅ Workflows use GitHub Actions standard patterns
• ✅ All defaults match original behavior (backward compatible)
• ✅ Variables are optional (workflows work without configuration)

Files Changed

• .github/workflows/claude.yml - Security + parameterization
• .github/workflows/claude-code-review.yml - Security + parameterization
• .github/CLAUDE_WORKFLOWS.md - Configuration documentation (new)

Example Usage

Restrict to repository owners only:
```bash

Settings → Secrets and variables → Actions → Variables

CLAUDE_AUTHORIZED_ROLES = ["OWNER"]
CLAUDE_REVIEW_AUTHORIZED_ROLES = ["OWNER"]
```

Use custom trigger:
```bash
CLAUDE_MENTION_TRIGGER = @bot
```

See .github/CLAUDE_WORKFLOWS.md for more examples and complete documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f2d3f3ca55

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use issue.author_association for issues trigger

For the issues event, the webhook payload exposes the author association on the issue (github.event.issue.author_association), not on sender. With github.event.sender.author_association here, the expression evaluates to null and contains(...) returns false, so the workflow never runs for newly opened issues even when the issue author is OWNER/MEMBER/COLLABORATOR. This breaks issue-triggered @claude mentions; switch the check to github.event.issue.author_association to restore the intended behavior.

Useful? React with 👍 / 👎.

[simonheimlicher]

@codex: Review this PR. It should address the following concern you raised on a private repository for the original version of the workflow:

The job runs whenever a comment/body contains @claude, but there is no check on author_association or any other trust signal. That means in a public repo any external commenter can trigger a workflow that uses CLAUDE_CODE_OAUTH_TOKEN, which conflicts with the intended “only users with write access can trigger” behavior and exposes the token to untrusted triggering (cost/abuse risk). Consider gating the if on author_association (e.g., MEMBER, OWNER, COLLABORATOR) or on a pull_request_target/label-based allowlist.

[claude]

Claude finished @simonheimlicher's task in 1m 39s —— View job

---

Code Review Complete ✅

I've reviewed the security fixes and parameterization changes. Here's my analysis:

---

🔒 Security Review

✅ Security Vulnerability Successfully Addressed

The PR correctly fixes the critical security issue where any external user could trigger workflows with access to CLAUDE_CODE_OAUTH_TOKEN. The implementation adds proper authorization checks for all event types.

What Changed:

• Before: No authorization checks - any user could trigger workflows
• After: Authorization checks on all triggers using author_association verification

🚨 CRITICAL BUG: Issues Event Authorization

The codex review comment is correct. There's a bug in .github/workflows/claude.yml:34:

# Line 34 - INCORRECT:
(github.event_name == 'issues' && ... &&
 contains(..., github.event.sender.author_association))

Problem: For the issues event, the webhook payload provides github.event.issue.author_association, not github.event.sender.author_association. Using sender.author_association evaluates to null, causing contains() to return false, which completely blocks all issue triggers even for authorized users.

Impact: The @claude mention feature is completely broken for:

• New issues (opened event)
• Assigned issues (assigned event)

Fix Required: Change line 34 from:

contains(fromJSON(vars.CLAUDE_AUTHORIZED_ROLES || '["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.sender.author_association)

To:

contains(fromJSON(vars.CLAUDE_AUTHORIZED_ROLES || '["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.issue.author_association)

Fix this →

---

✅ Authorization Check Analysis

Here's the authorization implementation for each event type:

Event Type	Authorization Field	Status
issue_comment	github.event.comment.author_association	✅ Correct
pull_request_review_comment	github.event.comment.author_association	✅ Correct
pull_request_review	github.event.review.author_association	✅ Correct
issues	github.event.sender.author_association	❌ Wrong (should be issue.author_association)

claude-code-review.yml:

Event Type	Authorization Field	Status
pull_request	github.event.pull_request.author_association	✅ Correct

---

🎛️ Parameterization Review

✅ Excellent Implementation

The parameterization is well-designed and follows GitHub Actions best practices:

Strengths:

1. DRY principle: Authorization roles defined once instead of repeated 5+ times
2. Sensible defaults: All variables have secure defaults that maintain backward compatibility
3. Optional configuration: Variables work without any configuration required
4. Clear naming: Variable names are descriptive and follow conventions
5. Good fallback handling: Uses vars.VAR || 'default' pattern correctly
6. Security-first defaults: Restrictive authorization and tool access by default

Configuration Variables:

claude.yml:

• CLAUDE_AUTHORIZED_ROLES - Who can trigger (default: ["OWNER", "MEMBER", "COLLABORATOR"])
• CLAUDE_MENTION_TRIGGER - Trigger word (default: @claude)
• CLAUDE_CONCURRENCY_CANCEL - Cancel in-progress runs (default: false)
• CLAUDE_ALLOWED_TOOLS - Tool restrictions (default: unrestricted)
• CLAUDE_CUSTOM_PROMPT - Override default behavior (default: empty)

claude-code-review.yml:

• CLAUDE_REVIEW_AUTHORIZED_ROLES - Who can trigger reviews
• CLAUDE_REVIEW_CONCURRENCY_CANCEL - Cancel in-progress reviews
• CLAUDE_REVIEW_ALLOWED_TOOLS - Tool restrictions (default: gh read-only + comment)
• CLAUDE_REVIEW_CUSTOM_PROMPT - Custom review instructions

---

📚 Documentation Review

✅ Comprehensive and Well-Structured

The new .github/CLAUDE_WORKFLOWS.md file is excellent:

Strengths:

1. Complete coverage: Documents all variables with type, default, description, and examples
2. Security focus: Dedicated security section with best practices
3. Practical examples: 5 real-world configuration scenarios
4. Troubleshooting: Helpful debugging section
5. Clear instructions: Step-by-step guide for setting variables
6. Good formatting: Well-organized with clear sections

Suggestions (minor):

• Consider adding a "Quick Start" section at the top for users who just want the basics
• Add a table of contents for easier navigation (optional for a 200-line doc)

---

🔐 Security Best Practices Review

✅ Security Controls Implemented:

1. Authorization checks: ✅ Implemented (with one bug to fix)
2. Concurrency controls: ✅ Prevents workflow spam
3. Tool restrictions: ✅ Configurable via variables
4. Default tool restrictions for reviews: ✅ Limited to read-only gh commands
5. Secure defaults: ✅ Only trusted roles can trigger

💡 Additional Security Recommendations:

1. Rate limiting: Consider adding workflow rate limits beyond concurrency (GitHub doesn't provide native rate limiting per user)
2. Audit logging: Document that workflow runs are logged in Actions tab for security auditing
3. Token rotation: Document token rotation procedures in CLAUDE_WORKFLOWS.md (already mentioned in best practices ✅)

---

🐛 Issues Summary

Critical Issues:

1. .github/workflows/claude.yml:34 - Wrong author_association field for issues event (breaks issue triggers completely)

No Other Issues Found:

• ✅ YAML syntax is valid
• ✅ No security vulnerabilities beyond the bugs identified
• ✅ Proper use of GitHub Actions patterns
• ✅ Good error handling with fallback defaults
• ✅ Backward compatible (existing workflows work without configuration)

---

📋 Recommendations

Must Fix (Critical):

1. Fix line 34 in claude.yml to use github.event.issue.author_association

Optional Improvements:

1. Add workflow tests to prevent similar bugs (test each event type with example payloads)
2. Add a note in CLAUDE_WORKFLOWS.md about the webhook payload differences between event types
3. Consider adding a validation script that checks authorization fields for each event type

---

✅ Verdict

Overall: This is a high-quality PR that successfully addresses the critical security vulnerability and adds comprehensive parameterization. The implementation is well-designed, thoroughly documented, and follows best practices.

Status: ⚠️ Needs one critical fix before merge (the issues event authorization bug)

Once the line 34 bug is fixed, this PR is ready to merge! 🚀

---

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".