claude-code-action/prds/5-dedicated-forgejo-user.md

PRD #5: Dedicated Forgejo User for Claude Bot

Issue: #5 Priority: High Created: 2026-02-25 Status: ~85% complete — code and infra done, pending E2E validation after merge

---

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
  • Evidence: User ID 48, is_admin: false, avatar set to Claude logo

• 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
  • Evidence: Claude team with write permission created in all 12 orgs, token validated (comment create/delete on issue #5, push: true on k8s/flux, crossplane/harbor-resources)

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
  • Evidence: CLAUDE_BOT_TOKEN org secret in all 12 orgs, claude.yml updated with bot_id: "48", bot_name: "claude-bot", bot_email: "claude@wxs.ro". New bot_email input added to action.yml.
  • Pending E2E: Trigger a real @claude mention to verify 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
  • Evidence: git-config.ts uses user.email when provided (falls back to noreply), context.ts reads BOT_EMAIL env var, all call sites pass botEmail. 794 tests pass.
  • Pending E2E: Trigger a tag-mode response that creates a branch to verify commit authorship

Phase 3: Documentation & Hardening

• [~] M5: Update documentation and test across repos
  • Update docs/forgejo.md with bot user setup instructions (full 6-step guide added)
  • 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

Implementation Notes

New bot_email Action Input

Added bot_email input to action.yml — when set, overrides the default noreply email format ({id}+{name}@users.noreply.{host}). On Forgejo, setting this to the bot user's registered email links commits to the bot's profile in the UI.

Org-Level Secrets

CLAUDE_BOT_TOKEN is stored as an org-level secret (not repo-level) in all 12 orgs with visibility: "all". This means any new repo in any org will automatically have access.

Team Structure

Each org has a Claude team with write permission on all repositories (includes_all_repositories: true). New repos are automatically covered.