Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
chore: trim .github/CLAUDE.md, remove local security model (#2011)
Maximilian Roos1134ca8128b5
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.mdindex b30c48c99..8f6a5b8df 100644--- a/.github/CLAUDE.md+++ b/.github/CLAUDE.md@@ -1,91 +1,30 @@-# CI Automation Security Model — Worktrunk+# CI Automation — Worktrunk-See [tend-security-model.md](tend-security-model.md) for the generic security model-(security layers, token management, prompt injection, event types, workflow-modification rules). This file documents worktrunk-specific configuration.+See [tend's security model](https://github.com/max-sixty/tend/blob/main/docs/security-model.md)+for the generic security model. This file documents worktrunk-specific+configuration.## Bot identity-`worktrunk-bot` is a regular GitHub user account (PAT-based), not a GitHub App.+`worktrunk-bot` — a regular GitHub user account (PAT-based, not a GitHub App).Workflows check `user.login == 'worktrunk-bot'` directly.## Tokens-| Token | Used by |+| Token | Purpose ||-------|---------|-| `WORKTRUNK_BOT_TOKEN` | All Claude workflows — consistent identity (`worktrunk-bot`) |-| `CLAUDE_CODE_OAUTH_TOKEN` | All — authenticates Claude Code to the Anthropic API |+| `WORKTRUNK_BOT_TOKEN` | All Claude workflows — consistent bot identity |+| `CLAUDE_CODE_OAUTH_TOKEN` | Authenticates Claude Code to the Anthropic API |## Merge restriction-### 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)--`worktrunk-bot` has `write` role (`admin: false`, `maintain: false`). Only the-repo owner (`@max-sixty`, admin) can merge. 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 silently skips the rule for the admin — no "bypass-branch protections" checkbox.--### Classic branch protection--- **Required reviews**: none (the ruleset is the merge restriction)-- **Required status checks**: `test (linux)`, `test (macos)`, `test (windows)`-- **Enforce admins**: off--**Why not CODEOWNERS?** Deadlock for solo maintainers: the code owner can't-approve their own PRs. The "Restrict updates" ruleset is simpler: one rule, one-bypass actor, CI remains enforced for everyone.--**Why not "Restrict who can push"?** Only available for org-owned repos. This-is a personal repo (`max-sixty/worktrunk`).+Only the repo owner (`@max-sixty`, admin) can merge to `main`.+`worktrunk-bot` has `write` role only. Enforced by a "Merge access" ruleset+(restrict updates, admin bypass in exempt mode). Required status checks:+`test (linux)`, `test (macos)`, `test (windows)`.## Environment protection`CARGO_REGISTRY_TOKEN` and `AUR_SSH_PRIVATE_KEY` are in a protected GitHub-Environment (`release`) requiring deployment approval from `@max-sixty`. The-environment has a deployment branch policy restricting to `v*` tags.--## Triage ↔ mention handoff--New issues are always handled by `tend-triage` — `tend-mention` only-triggers on issue **edits** (not opens) to avoid two workflows racing to create-fix PRs for the same bug.--- **New issue** (opened) → triage, regardless of `@worktrunk-bot` mentions-- **Issue edited** to add `@worktrunk-bot` → mention-- **Comment** on an issue/PR → mention (via `issue_comment` trigger)--The mention workflow runs for any user who includes `@worktrunk-bot` — the merge-restriction is the safety boundary, not access control on the workflow.--## Bot-engaged auto-response--**Triggers a response:**-- Non-draft PR opened or updated → automatic code review (`tend-review`)-- Formal review submitted on a `worktrunk-bot`-authored PR, with body or non-approval → `tend-review` responds-- `@worktrunk-bot` mentioned in a new issue body → `tend-triage` handles it-- `@worktrunk-bot` mentioned via issue edit → `tend-mention` responds-- `@worktrunk-bot` mentioned in any comment → `tend-mention` responds-- Comment on a PR/issue where `worktrunk-bot` has engaged → `tend-mention` runs, responds only if helpful-- Editing a comment or issue body re-triggers the mention workflow--**Does not trigger:**-- `worktrunk-bot`'s own comments (workflow-level loop prevention)-- Empty approvals on `worktrunk-bot` PRs-- Comments on issues/PRs where `worktrunk-bot` hasn't engaged and no mention-- Draft PRs--**Loop prevention for bot reviews:** Bot-authored reviews and review comments-are no longer filtered at the workflow level (removed in tend#168 to allow the-bot to apply its own review suggestions). Instead, the prompt includes-self-conversation loop prevention: the bot exits silently unless there is a-distinct role boundary (e.g., reviewer on its own PR).--**Routing:** Formal reviews (`pull_request_review`) → `tend-review`. Inline-comments (`pull_request_review_comment`) and conversation comments-(`issue_comment`) → `tend-mention`.+Environment (`release`) requiring deployment approval from `@max-sixty`,+restricted to `v*` tags.diff --git a/.github/tend-security-model.md b/.github/tend-security-model.mddeleted file mode 100644index 89d0b0114..000000000--- a/.github/tend-security-model.md+++ /dev/null@@ -1,150 +0,0 @@-# CI Automation Security Model--Generic security model for Claude-powered CI workflows. This document covers-the principles; each adopting repo should document its specific configuration-(admin accounts, token names, protected environments) in its own `.github/CLAUDE.md`.--## Security layers--Two layers protect a repository, in order of importance:--1. **Merge restriction** — only designated admins can merge to the default- branch, enforced by a ruleset or branch protection. The bot has write access- (not admin) and cannot merge regardless of review status.-2. **Environment protection** — release secrets (registry tokens, signing keys)- are in a protected GitHub Environment requiring deployment approval,- preventing exfiltration via modified workflows.--Token scoping (principle of least privilege) is a secondary practice, not a-security boundary.--## What each workflow needs to do--| Capability | Triage | Mention | Review | CI Fix | Nightly | Renovate |-|------------|:---:|:---:|:---:|:---:|:---:|:---:|-| Read issues/PRs | Yes | Yes | Yes | Yes | Yes | — |-| Comment on issues | Yes | Yes | Yes | — | Yes | — |-| Create branches | Yes | Yes | Yes | Yes | Yes | Yes |-| Push commits | Yes | Yes | Yes | Yes | Yes | Yes |-| Create PRs | Yes | Yes | — | Yes | Yes | Yes |-| Post PR reviews | — | — | Yes | — | — | — |-| Resolve review threads | — | — | Yes | — | — | — |-| Monitor CI | Yes | Yes | Yes | Yes | Yes | Yes |-| **Pushes must trigger CI** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |--The last row matters: `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 or GitHub App installation token.--## Token assignment--Use a single bot token across all Claude workflows for consistent identity.-The merge restriction (ruleset) caps blast radius regardless of which token-is used.--Two tokens are needed:--| Token | Purpose |-|-------|---------|-| Bot token (PAT or App) | GitHub API and git operations. Consistent bot identity. |-| Claude OAuth token | Authenticates Claude Code to the Anthropic API. |--### Why one bot token--The bot token is equally safe in any workflow because the merge restriction-caps the blast radius. Using a single token gives 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 (PAT) | Long-lived | Push to unprotected branches, create PRs, impersonate bot — **indefinitely** | Merge PRs (merge restriction), push to default branch, access release secrets (environment-protected) |-| Bot token (App) | ~1 hour | Same as PAT, but only until token expires | Same + token auto-expires |-| Claude OAuth | 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:-- Merge restriction blocks merging by non-admins-- Environment protection blocks exfiltration of release secrets-- With a GitHub App, tokens auto-expire in ~1 hour-- With a PAT, rotate 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, that token'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.--All workflows should pass the bot token to both paths.--## Prompt injection threat model--| Workflow | Injection surface | Attacker control | Mitigations |-|----------|-------------------|-------------------|-------------|-| **review** | PR diff content, review body on bot PRs | Full (any PR) / Medium (reviewers) | Fixed prompt, merge restriction |-| **triage** | Issue body | Partial (structured skill) | Fixed prompt, merge restriction, environment protection |-| **mention** | Comment body on any issue/PR | Full | Fixed prompt, merge restriction, engagement verification |-| **ci-fix** | Failed CI logs | Minimal (must break CI on default branch) | 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 a secret-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.--## Future hardening--- Migrate from PAT to GitHub App for ephemeral tokens (~1 hour vs indefinite)-- Workflow dispatch isolation: split workflows into analysis (GITHUB_TOKEN) +- push (separate workflow with bot token) so the token never touches untrusted- input-- Disable "Allow GitHub Actions to create and approve pull requests" in repo- settings--## GitHub API: event types for PR comments--GitHub treats PRs as a superset of issues. Comments on a PR arrive via-different event types depending on where they're posted:--- **Conversation tab** → `issue_comment` event. The PR is at- `github.event.issue.pull_request`. 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`.-- **Review submission** → `pull_request_review` event (type: `submitted`). The- review is at `github.event.review`. The PR is at- `github.event.pull_request`.--Individual inline comments from a review also fire as separate-`pull_request_review_comment` events.--## Rules for modifying workflows--- **No role-based gating**: Don't check `author_association` (OWNER, MEMBER,- etc.) to decide whether to run. The merge restriction is the security- boundary. Use technical criteria: fork detection, loop prevention, trigger- phrases.-- **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 /tend-running-in-ci before starting work."`.-- **Token choice**: All Claude workflows use the bot token for consistent- identity.-- **`permissions:` block**: Set `contents: read` for read-only workflows.-- **Sensitive secrets** must be in protected environments, never repo-level.