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

---

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