docs(prd): create PRDs #5, #6, #7 for Forgejo hardening [skip ci]

- PRD #5: Dedicated Forgejo user for Claude bot (dedicated identity, scoped token) - PRD #6: E2E test all 5 untested Forgejo trigger scenarios - PRD #7: Senior developer review of all Forgejo platform support code - Defined 5, 7, and 6 milestones respectively - All three can be parallelized (#7 is read-only, runs alongside #5) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 20:13:57 +02:00
1 parent 54c2d5b3e8
commit 34c259f189
@@ -0,0 +1,88 @@
+# PRD #5: Dedicated Forgejo User for Claude Bot
+
+**Issue**: [#5](https://git.wxs.ro/actions/claude-code-action/issues/5)
+**Priority**: High
+**Created**: 2026-02-25
+
+---
+
+## Problem
+
+Claude currently runs under the human operator's personal Forgejo token (`FORGEJO_TOKEN` / `github_token`). This causes:
+
+1. **Attribution confusion**: Commits and comments appear as the human user, not as a bot
+2. **Over-privileged access**: The bot inherits all permissions of the human account
+3. **Audit trail**: No clear separation between human actions and bot actions in repo history
+4. **Security**: If the action is compromised, the human's full token is exposed
+
+On GitHub, this is solved by the GitHub App OIDC token exchange (bot gets its own `claude[bot]` identity). On Forgejo, there's no such mechanism — we need a manual equivalent.
+
+## Solution
+
+Create a dedicated `claude-bot` user on the Forgejo instance (git.wxs.ro), generate a scoped API token for it, and configure the action workflow to use that token. This gives Claude its own identity for commits, comments, and API operations.
+
+## Milestones
+
+### Phase 1: Forgejo Admin Setup
+
+- [ ] **M1: Create dedicated `claude-bot` user on git.wxs.ro**
+
+  - Create user via Forgejo admin panel or API (`POST /admin/users`)
+  - Set appropriate display name (e.g., "Claude Bot")
+  - Set avatar to distinguish from human users
+  - User should NOT have admin privileges
+  - **Validation**: User exists and can log in
+
+- [ ] **M2: Configure bot user permissions and token**
+  - Add `claude-bot` to the `actions` org (and any other orgs where the action runs)
+  - Grant `write` permission on repos where Claude needs to operate
+  - Generate a scoped API token for the bot user with minimal required permissions:
+    - `repo` (read/write issues, PRs, comments, branches, commits)
+    - `packages` (if needed for container operations)
+    - NO admin scope, NO user scope beyond what's needed
+  - **Validation**: Token can create comments and push branches on a test repo
+
+### Phase 2: Action Configuration
+
+- [ ] **M3: Update workflow to use bot token**
+
+  - Store the bot token as a Forgejo Actions secret (e.g., `CLAUDE_BOT_TOKEN`)
+  - Update `claude.yml` workflow to pass `github_token: ${{ secrets.CLAUDE_BOT_TOKEN }}` instead of the human token
+  - Update `bot_id` and `bot_name` inputs to match the new Forgejo user's ID and username
+  - Document the token rotation procedure
+  - **Validation**: Action runs with bot token, comments appear as `claude-bot`
+
+- [ ] **M4: Verify git commit attribution**
+  - Ensure `git config user.name` and `user.email` use the bot user's identity
+  - Verify that `src/github/operations/git-config.ts` correctly picks up the bot user info from the token
+  - Test that pushed commits show the bot user as author in Forgejo UI
+  - **Validation**: A tag-mode response that creates a branch shows `claude-bot` as commit author
+
+### Phase 3: Documentation & Hardening
+
+- [ ] **M5: Update documentation and test across repos**
+  - Update `docs/forgejo.md` with bot user setup instructions
+  - Document token rotation procedure (tokens expire, need renewal plan)
+  - Test the bot user setup on at least one additional repo beyond `claude-code-action`
+  - Update `CLAUDE.md` if any workflow changes affect development
+  - **Validation**: Another developer can follow the docs to set up the bot user on a new Forgejo instance
+
+## Dependencies
+
+- Forgejo admin access to git.wxs.ro (to create the user)
+- Understanding of Forgejo's permission model (org membership, repo access)
+
+## Risks
+
+| Risk                                    | Mitigation                                                             |
+| --------------------------------------- | ---------------------------------------------------------------------- |
+| Token expiration                        | Document rotation procedure, set long-lived token or calendar reminder |
+| Bot user locked out                     | Keep admin access to reset password/token                              |
+| Permission too narrow                   | Start with `write` on repos, expand only if needed                     |
+| Bot user confused with human in reviews | Set clear display name and avatar                                      |
+
+## Success Criteria
+
+- All Claude comments and commits on Forgejo repos appear as `claude-bot`, not the human user
+- The bot token has minimal scoped permissions (no admin access)
+- Documentation allows reproducing the setup on a fresh Forgejo instance