Forgejo Codex Agent

Self-hosted service that lets trusted Forgejo users trigger Codex work by assigning an issue to the bot or mentioning @<bot> in an issue comment. It can receive Forgejo webhooks or poll the bot account's unread issue notifications. The service runs Codex in a disposable clone, then pushes a codex/issue-... branch and opens a WIP: pull request.

Commands

vp install
vp run agent:dev
vp run agent:register-hook
vp run build
vp run agent:start

agent:register-hook requires WEBHOOK_PUBLIC_URL, WEBHOOK_ENABLED=true, and explicit ALLOWED_REPOS entries. The webhook endpoint is POST /webhooks/forgejo; health checks are available at GET /healthz and GET /readyz.

Configuration

Create a .env file with the service environment. The service scripts load .env automatically when it exists. Required values are:

• FORGEJO_BASE_URL
• FORGEJO_BOT_USERNAME
• FORGEJO_WRITE_TOKEN
• TRUSTED_USERS
• ALLOWED_REPOS

FORGEJO_WEBHOOK_SECRET is required when WEBHOOK_ENABLED=true. For polling-only mode, set POLL_NOTIFICATIONS=true and WEBHOOK_ENABLED=false; no public URL, tunnel, or Forgejo webhook is needed.

FORGEJO_READ_TOKEN defaults to FORGEJO_WRITE_TOKEN when omitted. Codex authentication can come from CODEX_API_KEY, CODEX_ACCESS_TOKEN, or an existing Codex CLI login on the host. Prefer a persisted Codex login or CODEX_ACCESS_TOKEN on a trusted host; if CODEX_API_KEY is used, the agent constrains Codex tool-command environment inheritance.

Forgejo Setup

Create a dedicated bot account and add it to every repository in ALLOWED_REPOS with permission to clone, push branches, comment on issues, and open pull requests. If you want to use vp run agent:register-hook, the bot must also be a repository admin so it can create webhooks.

Create the access token from Settings | Applications | Generate New Token, as described in Forgejo's API token documentation. Use these token scopes:

• FORGEJO_WRITE_TOKEN: write:repository and write:issue. This token is used for authenticated git push, pull request creation, issue comments, and webhook registration.
• FORGEJO_READ_TOKEN: optional read:repository token for cloning repositories. Omit it to reuse FORGEJO_WRITE_TOKEN.

For notification polling, the bot token also needs notification access, typically read:notification to list notification threads and write:notification to mark processed threads read.

If you restrict token repository access, include every repository listed in ALLOWED_REPOS. Forgejo restricts some repository-admin operations for "Specific repositories" tokens, so automatic webhook registration may require a token with broader repository access even when the bot account itself is limited to the target repositories.

You can register hooks with WEBHOOK_PUBLIC_URL=https://agent.example.com/webhooks/forgejo and vp run agent:register-hook, or create them manually from each repository's Settings | Webhooks page using Forgejo's webhook documentation. Manual hook settings are:

• Type: Forgejo
• Target URL: https://agent.example.com/webhooks/forgejo
• POST Content Type: application/json
• Secret: the same value as FORGEJO_WEBHOOK_SECRET
• Trigger On: Issues, Issue Assign, and Issue Comment events

Polling mode uses GET /api/v1/notifications, PATCH /api/v1/notifications/threads/{id}, issue/comment fetches, and issue timelines. It queues trusted @<bot> issue comments from notification latest_comment_url; assignment notifications queue only when the issue is assigned to the bot and the timeline shows a trusted assigning user, falling back to a trusted issue author when Forgejo does not expose a specific assignment event.

CODEX_SANDBOX defaults to workspace-write. Set it to danger-full-access only when the agent runs in an isolated environment you are comfortable letting Codex modify, because it disables Codex filesystem sandboxing inside the disposable clone job.

Safety Model

The service verifies X-Forgejo-Signature for webhook mode, deduplicates webhook deliveries and notification threads, ignores bot-authored events, requires trusted trigger users, and ignores pull request comments. Forgejo tokens are used only by the service process for clone, push, comments, hooks, PR creation, and notification polling; they are not passed to the Codex subprocess.