Skip to content

Gitea

Connect Archon to a self-hosted Gitea instance so you can interact with your AI coding assistant from Gitea issues and pull requests.

  • Archon server running (archon serve; see Web UI)
  • A Gitea instance with API access enabled
  • A Gitea personal access token (or dedicated bot account token)
  • Public endpoint for webhooks (or a tunnel for local development)
  1. Log in to your Gitea instance
  2. Go to Settings > Applications > Manage Access Tokens
  3. Create a new token with repository read/write permissions
  4. Copy the token — you will need it for Step 3

On Linux/Mac:

Terminal window
openssl rand -hex 32

On Windows (PowerShell):

Terminal window
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

Save this secret for Steps 3 and 4.

GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_personal_access_token
GITEA_WEBHOOK_SECRET=your_secret_from_step_2

All three variables are required. The adapter starts automatically when all three are set.

Optional variables:

# Restrict who can trigger the bot (comma-separated usernames, case-insensitive)
GITEA_ALLOWED_USERS=alice,bob
# Custom @mention name (defaults to BOT_DISPLAY_NAME, then "Archon")
GITEA_BOT_MENTION=archon

Go to your repository settings in Gitea:

  • Navigate to Settings > Webhooks > Add Webhook > Gitea

Webhook Configuration:

FieldValue
Target URLhttps://your-domain.com/webhooks/gitea
HTTP MethodPOST
Content Typeapplication/json
SecretPaste the secret from Step 2
EventsIssues, Issue Comments, Pull Requests, Pull Request Comments

Click Add Webhook and use the Test Delivery button to verify connectivity.

Webhook bodies are limited to 32 MiB (33,554,432 bytes), inclusive. Larger bodies receive HTTP 413 and are not processed.

Interact by @mentioning the bot in issue or PR comments:

@archon can you analyze this bug?
@archon review this implementation
@archon /workflow run archon-investigate "why does the auth flow reject valid tokens?"

First mention behavior:

  • Reuses an existing local registration at its saved checkout path. Otherwise, registers and clones the repository to ~/.archon/workspaces/
  • Detects and loads commands from .archon/commands/ if present
  • Injects full issue/PR context (title, description, labels) for the AI assistant

Subsequent mentions:

  • Resumes the existing conversation
  • Maintains full context across comments

The Gitea adapter is a webhook-based forge adapter, similar to the GitHub adapter:

  • Transport: Receives HTTP POST webhooks from Gitea
  • Signature verification: HMAC SHA-256 over the exact received bytes, using the X-Gitea-Signature header
  • Streaming mode: Always batch (assembles the assistant reply after processing; long replies may span multiple comments; see batch mode for filtering and fallback behavior)
  • Conversation ID format: owner/repo#number for issues, owner/repo!number for PRs
  • Self-loop prevention: Bot comments include a hidden HTML marker (<!-- archon-bot-response -->) to avoid re-triggering on its own messages
  • Retry logic: Transient network errors (timeouts, connection resets) are retried up to 3 times with exponential backoff

When an issue is closed or a PR is merged/closed, the adapter automatically cleans up any associated worktree isolation environment.

Add a webhook with the same secret to each repository you want the bot to monitor. The webhook secret must be identical across all repos pointing to the same Archon instance.

  • Configuration — Full environment variable reference
  • Security — Webhook verification and authorization details