Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

CI security model: rulesets, token consolidation, environment protection (#1118)

Maximilian Roosbd188aa7efc9
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
new file mode 100644
index 000000000..955d77492
--- /dev/null
+++ b/.github/CLAUDE.md
@@ -0,0 +1,153 @@
+# CI Automation Security Model
+
+Five Claude-powered workflows automate issue triage, PR review, CI fixes, dependency updates, and `@claude` mentions.
+
+## Security layers
+
+Two layers protect the repository, in order of importance:
+
+1. **Merge restriction** (implemented) — only the repo admin (`@max-sixty`) can merge to `main`, enforced by a ruleset. The bot has `write` role (not admin) and cannot merge regardless of review status.
+2. **Environment protection** (planned) — release secrets will require deployment approval, preventing exfiltration via modified workflows. Currently these are repo-level secrets — see TODO.
+
+Token scoping (principle of least privilege) is a secondary practice, not a security boundary.
+
+## Branch protection on `main`
+
+### Classic branch protection (current)
+
+- **Required reviews**: 1 approval
+- **Required status checks**: `test (linux)`, `test (macos)`, `test (windows)`
+- **Enforce admins**: off
+
+### Ruleset: "Merge access"
+
+- **Rule**: Restrict updates — only bypass actors can push to or merge into `main`
+- **Bypass**: Repository Admin role → **exempt** mode (silent, no checkbox)
+
+The admin/write role distinction is the merge restriction. `worktrunk-bot` has `write` role (`admin: false`, `maintain: false`). Only the repo owner (`@max-sixty`, admin) can merge. This is enforced by the "Restrict updates" rule — GitHub treats merging a PR as a push to the base branch, so restricting updates blocks both direct pushes and PR merges.
+
+The "exempt" bypass mode (added September 2025) silently skips the rule for the admin — no "bypass branch protections" checkbox. This differs from the older "always" bypass mode, which showed a disruptive checkbox on every merge.
+
+**Why not CODEOWNERS?** CODEOWNERS creates a deadlock for solo maintainers: the code owner can't approve their own PRs (GitHub blocks self-approval), and there's no other code owner. Solving this requires `enforce_admins=off` which also bypasses CI checks, or a separate bypass ruleset which adds complexity. The "Restrict updates" ruleset is simpler: one rule, one bypass actor, CI remains enforced for everyone.
+
+**Why not "Restrict who can push" (classic branch protection)?** That feature is only available for organization-owned repositories. This is a personal repo (`max-sixty/worktrunk`).
+
+## Environment protection for release secrets (planned)
+
+`CARGO_REGISTRY_TOKEN` and `AUR_SSH_PRIVATE_KEY` should be stored in a protected GitHub Environment (`release`) requiring deployment approval from `@max-sixty`. **These are currently repo-level secrets** — see TODO.
+
+**Why this matters:** If BOT_TOKEN leaks, an attacker can push a branch with a modified workflow that references `${{ secrets.CARGO_REGISTRY_TOKEN }}`. For same-repo PRs (not forks), all repo-level secrets are available to workflows. The modified workflow runs from the PR branch at CI time — before any merge. Branch protection doesn't prevent this because the secret leaks during CI, not at merge time.
+
+Environment protection prevents this: secrets in a protected environment are only available to jobs that reference that environment AND pass the protection rules (manual approval).
+
+## What each workflow needs to do
+
+| Capability | Triage | Mention | Review | CI Fix | Renovate |
+|------------|:---:|:---:|:---:|:---:|:---:|
+| Read issues/PRs | Yes | Yes | Yes | Yes | — |
+| Comment on issues | Yes | Yes | — | — | — |
+| Create branches | Yes | Yes | — | Yes | Yes |
+| Push commits | Yes | Yes | — | Yes | Yes |
+| Create PRs | Yes | Yes | — | Yes | Yes |
+| Post PR reviews | — | — | Yes | — | — |
+| Resolve review threads | — | — | Yes | — | — |
+| Monitor CI | Yes | Yes | — | Yes | Yes |
+| **Pushes must trigger CI** | **Yes** | **Yes** | — | **Yes** | **Yes** |
+
+The last row matters for CI: `GITHUB_TOKEN` pushes don't trigger downstream workflows (GitHub prevents infinite loops). Workflows that push code and need CI to run **must** use a PAT. All Claude workflows use `WORKTRUNK_BOT_TOKEN` for consistent identity.
+
+## Token assignment
+
+| Token | Used by | Why |
+|-------|---------|-----|
+| `WORKTRUNK_BOT_TOKEN` | all Claude workflows | Consistent identity (`worktrunk-bot`). The merge restriction (ruleset) is the security boundary, not token scoping. |
+| `CLAUDE_CODE_OAUTH_TOKEN` | all | Authenticates Claude Code to the Anthropic API. |
+
+### Why one token
+
+BOT_TOKEN is equally safe in any workflow: the merge restriction (ruleset) caps the blast radius regardless of which token is used. Using BOT_TOKEN everywhere gives a consistent identity for reviews and comments, and avoids the `github-actions[bot]` branding.
+
+### If a token leaks
+
+| Token | Lifetime | If leaked, attacker can... | ...but cannot |
+|-------|----------|---------------------------|---------------|
+| `BOT_TOKEN` | Long-lived PAT | Push to unprotected branches, create PRs, approve non-own PRs, impersonate `worktrunk-bot` — **indefinitely** | Merge PRs (ruleset restricts updates to admin), push to `main`. Once environment protection is implemented: access release secrets. |
+| `CLAUDE_CODE_OAUTH_TOKEN` | Long-lived | Run Claude sessions billed to the account | Access GitHub |
+
+`GITHUB_TOKEN` is ephemeral (single job) and automatically scoped by each workflow's `permissions:` block. Not a meaningful leak target.
+
+**BOT_TOKEN is the high-value target.** Mitigations:
+- "Restrict updates" ruleset blocks merging by non-admins
+- Environment protection will block exfiltration of release secrets (once implemented — see TODO)
+- Rotate `BOT_TOKEN` periodically
+
+### How tokens interact with `permissions:` and `actions/checkout`
+
+Two independent authentication paths exist in every workflow:
+
+1. **Git CLI** (`git push`): authenticates with the token from `actions/checkout`. When no explicit token is passed, this defaults to `GITHUB_TOKEN` scoped by the `permissions:` block. When an explicit token is passed (e.g. `token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}`), the PAT's scopes apply instead.
+2. **GitHub API** (`gh pr create`, `gh api`): `claude-code-action` overwrites the `GITHUB_TOKEN` env var with its `github_token` input (BOT_TOKEN for all Claude workflows).
+
+The review workflow is the only one where these paths diverge: checkout uses the default `GITHUB_TOKEN` (`contents: read`), so git CLI is read-only, while API calls use BOT_TOKEN. All other workflows pass BOT_TOKEN to both paths.
+
+## Prompt injection threat model
+
+| Workflow | Injection surface | Attacker control | Mitigations |
+|----------|-------------------|-------------------|-------------|
+| **review** | PR diff content | Full (any external PR) | Fixed prompt, merge restriction, `contents: read` on checkout |
+| **triage** | Issue body | Partial (structured skill) | Fixed prompt, merge restriction, environment protection |
+| **mention** | Comment body | Full | Restricted to write-access users |
+| **ci-fix** | Failed CI logs | Minimal (must break CI on main) | Fixed prompt, automatic trigger |
+| **renovate** | None | None | Fixed prompt, scheduled trigger |
+
+### Secret exfiltration via modified workflows
+
+The most dangerous attack from a leaked BOT_TOKEN is not merging malicious code — it's exfiltrating other secrets:
+
+1. Push a branch with a modified workflow that references `${{ secrets.CARGO_REGISTRY_TOKEN }}`
+2. Create a PR — the modified workflow runs from the PR branch
+3. For same-repo PRs, all **repo-level** secrets are available
+4. Environment-protected secrets are NOT available (require deployment approval)
+
+This is why release secrets must be in a protected environment, not repo-level secrets.
+
+## TODO
+
+### Immediate
+
+- [x] Create "Merge access" ruleset on `main`: "Restrict updates" rule, bypass actor = Repository Admin with **exempt** mode. This prevents `worktrunk-bot` (write role) from merging while giving `@max-sixty` (admin) a frictionless merge button.
+- [x] Create `release` GitHub Environment with deployment protection (require `@max-sixty` approval). Add deployment branch/tag allowlist restricting to `v*` tags so arbitrary branches can't request the environment. Leave "prevent self-approvals" off (otherwise the tag pusher can't approve their own release).
+- [x] Move `CARGO_REGISTRY_TOKEN` and `AUR_SSH_PRIVATE_KEY` from repo secrets to the `release` environment. Update `release.yaml` `publish-cargo` and `publish-aur` jobs to add `environment: release`.
+- [x] Delete `WORKTRUNK_REVIEW_TOKEN` from repo secrets
+
+### Future hardening
+
+- [ ] Consider migrating from PAT to GitHub App for ephemeral tokens (~1 hour lifetime vs indefinite PAT)
+- [ ] Consider workflow dispatch isolation: split triage/mention into analysis (GITHUB_TOKEN) + push (separate workflow with BOT_TOKEN) so the token never touches untrusted input
+- [ ] Consider disabling "Allow GitHub Actions to create and approve pull requests" in repo settings to prevent GITHUB_TOKEN from ever approving PRs
+
+## Triage ↔ mention handoff
+
+These two workflows explicitly exclude each other to avoid double-processing:
+- Issue body contains `@claude` → triage skips, mention handles it
+- Issue body does not contain `@claude` → triage handles it, mention ignores it
+
+Consequence: external users (no write access) who open issues with `@claude` get **neither** triage nor a mention response. This is the accepted trade-off — `@claude` is a maintainer tool.
+
+## GitHub API: issue_comment vs pull_request_review_comment
+
+GitHub treats PRs as a superset of issues. Comments on a PR arrive via two different event types depending on where they're posted:
+
+- **Conversation tab** → `issue_comment` event. The PR is at `github.event.issue.pull_request` (a truthy object). The PR number is `github.event.issue.number`.
+- **Files changed (inline)** → `pull_request_review_comment` event. The PR is at `github.event.pull_request`. There is no `github.event.issue`.
+
+The `claude-mention` workflow handles both with separate checkout steps.
+
+## Rules for modifying workflows
+
+- **Adding `allowed_non_write_users`** to a workflow with user-controlled prompts requires security review.
+- **All Claude workflows** must include `--append-system-prompt "You are operating in a GitHub Actions CI environment. Use /running-in-ci before starting work."`.
+- **Token choice**: All Claude workflows use `BOT_TOKEN` for consistent identity. The merge restriction (ruleset) is the security boundary.
+- **`permissions:` block**: Set `contents: read` for read-only workflows.
+- **Sensitive secrets** must be in protected environments, never repo-level.
+- **Rotate `BOT_TOKEN`** periodically.
diff --git a/.github/workflows/claude-mention.yaml b/.github/workflows/claude-mention.yaml
index 0bea79aac..1592b4922 100644
--- a/.github/workflows/claude-mention.yaml
+++ b/.github/workflows/claude-mention.yaml
@@ -48,12 +48,18 @@ jobs:
git config --global user.name "Claude Code"
git config --global user.email "[email protected]"
- - name: 📌 Check out PR branch
+ - name: 📌 Check out PR branch (conversation comment)
if: github.event.issue.pull_request
run: gh pr checkout ${{ github.event.issue.number }}
env:
GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
+ - name: 📌 Check out PR branch (review comment)
+ if: github.event_name == 'pull_request_review_comment'
+ run: gh pr checkout ${{ github.event.pull_request.number }}
+ env:
+ GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
+
- name: Install cargo-insta
uses: baptiste0928/cargo-install@v3
with:
diff --git a/.github/workflows/claude-review.yaml b/.github/workflows/claude-review.yaml
index 885246ab0..f617fc654 100644
--- a/.github/workflows/claude-review.yaml
+++ b/.github/workflows/claude-review.yaml
@@ -26,7 +26,7 @@ jobs:
github.event.pull_request.user.type != 'Bot'
runs-on: ubuntu-24.04
permissions:
- contents: write
+ contents: read # Read-only: review workflow should not push code
pull-requests: write
issues: write
id-token: write
@@ -47,11 +47,12 @@ jobs:
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- github_token: ${{ secrets.WORKTRUNK_REVIEW_TOKEN }}
+ # BOT_TOKEN so reviews post as worktrunk-bot (not github-actions[bot]).
+ # Merge restriction (ruleset) is the security boundary, not token
+ # scoping. See .github/CLAUDE.md.
+ github_token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
additional_permissions: |
actions: read
- # TODO: sticky comment stopped appearing after switching to WORKTRUNK_REVIEW_TOKEN PAT.
- # Bot now puts feedback in review bodies instead of stdout, so this may be a no-op.
use_sticky_comment: true
prompt: |
Use /pr-review ${{ github.event.pull_request.number }}
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 739895926..bcb2f1db8 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -295,6 +295,7 @@ jobs:
- plan
- host
runs-on: ubuntu-24.04
+ environment: release
if: ${{ needs.plan.outputs.publishing == 'true' }}
steps:
- uses: actions/checkout@v6
@@ -360,6 +361,7 @@ jobs:
- plan
- host
runs-on: ubuntu-24.04
+ environment: release
if: ${{ needs.plan.outputs.publishing == 'true' }}
steps:
- uses: actions/checkout@v6