Gitea & Forgejo Integration

Connect Codeveira to a self-hosted Gitea or Forgejo instance. Because both platforms share the same REST API, the setup is identical for both — pick the correct webhook type for your platform and you're done.

Prerequisites

Before you start, make sure you have the following:

A self-hosted Gitea 1.20+ or Forgejo instance that is reachable from your Codeveira server
A personal access token on that instance (created in the next step)
Admin access to your Codeveira installation

Gitea and Forgejo share the same REST API. The integration setup in Codeveira is identical for both platforms — only the webhook type differs.

How Codeveira integrates with Gitea & Forgejo

Gitea and Forgejo share the same REST API, so the Codeveira integration is identical for both platforms. The integration works in two parts: a read-only API connection to fetch commit data, and a webhook that delivers push events in real time.

Read-only API access

Codeveira authenticates to your Gitea or Forgejo instance using a personal access token. All API calls are read-only — Codeveira never creates issues, modifies branches, or writes to your repositories. The token is used to:

Fetch commit metadata: author, message, timestamp, parent commit SHA
Download the raw diff for each commit for display in the review viewer
Retrieve repository details (default branch, description)
Read file content for syntax-highlighted diff display

In newer Gitea and Forgejo versions, use fine-grained tokens with only repository: Read permission. This is the minimum access needed and limits the token's scope if it is ever compromised.

Automatic review creation via webhooks

The webhook you configure in Step 3 delivers push events from Gitea or Forgejo to Codeveira's endpoint (/webhooks/gitea or /webhooks/forgejo). Codeveira and Forgejo share the same GITEA_WEBHOOK_SECRET because Forgejo sends a compatible signature header. When a push event arrives:

Codeveira verifies the HMAC-SHA256 signature from the X-Gitea-Signature header
It reads the list of commits included in the push
Consecutive commits by the same author are grouped into a single code review
The review is created and the diff is fetched from the API
Reviewers are notified and the AI reviewer bot (if configured) analyzes the diff

Webhooks are optional. Without a webhook you can still manually create code reviews from the Codeveira dashboard by browsing the repository's commits. The webhook makes the process automatic on every push.

Forgejo compatibility

Forgejo is a community fork of Gitea with identical API surface. Codeveira treats them as the same platform internally. The only difference is the webhook URL (/webhooks/forgejo instead of /webhooks/gitea) and the platform button you click when adding the repository in Codeveira. Both use the same GITEA_WEBHOOK_SECRET environment variable.

Create an access token

In your Gitea or Forgejo instance, generate a personal access token that Codeveira will use to read repository data:

Click your avatar in the top-right corner and go to Settings
Open the Applications tab
Under Generate New Token, enter a name such as Codeveira
Select the repository permission with Read access to contents
Click Generate Token and copy the value immediately — it is shown only once

In newer Gitea and Forgejo versions, use fine-grained tokens and grant only repository: Read — no write access is needed by Codeveira.

Add the repository in Codeveira

With the token in hand, register the repository inside Codeveira:

Go to Repositories → New Repository
Click Gitea or Forgejo to select the platform
Fill in the following fields:

Name — display name for the repository in Codeveira
Instance URL — base URL of your instance, e.g. https://gitea.example.com
Owner/Repo path — e.g. myorg/myrepo
Access Token — the token you generated in Step 1

The Instance URL is required. There is no global default for Gitea in most setups, although setting GITEA_URL in your .env file can act as a fallback value for new repositories.

Click Save. Codeveira will immediately attempt to fetch recent commits to verify the connection.

Configure the webhook

Webhooks allow Codeveira to automatically create a code review on every push without polling. Follow the instructions for your platform:

Gitea

In your Gitea repository go to Settings → Webhooks → Add webhook → Gitea
Set Target URL to: https://codeveira.yourdomain.com/webhooks/gitea
Set Secret to the value of GITEA_WEBHOOK_SECRET from your .env
Under Trigger On, select Push Events
Make sure Active is checked, then click Add Webhook

Forgejo

In your Forgejo repository go to Settings → Webhooks → Add webhook → Forgejo
Set Target URL to: https://codeveira.yourdomain.com/webhooks/forgejo
Set Secret to the value of GITEA_WEBHOOK_SECRET from your .env — this secret is shared by both Gitea and Forgejo
Under Trigger On, select Push Events
Make sure Active is checked, then click Add Webhook

Forgejo sends an X-Forgejo-Event header alongside the standard X-Gitea-Signature header. Codeveira reads both, so the same GITEA_WEBHOOK_SECRET works for both platforms without any extra configuration.

You can verify delivery by clicking Test Delivery on the webhook settings page after saving. A successful delivery returns HTTP 200.

Troubleshooting

"Host not reachable" on webhook delivery

Gitea or Forgejo must be able to reach your Codeveira instance over the network. If both services are self-hosted, check that there is no firewall rule blocking outbound HTTP/HTTPS from the Gitea/Forgejo server to the Codeveira server. Verify connectivity with:

curl -I https://codeveira.yourdomain.com/webhooks/gitea

"401 Unauthorized" when fetching commits

The access token has either expired or was created with insufficient permissions. Return to Settings → Applications in Gitea/Forgejo, delete the old token, and generate a new one with repository: Read access. Update the token in Codeveira → Repositories → Edit.

Commits show no diff

Ensure the token belongs to a user who has read access to the repository. For private repositories the repository owner must have granted access to the account that owns the token. Check that the Owner/Repo path saved in Codeveira matches the path shown in the Gitea/Forgejo URL exactly.

Webhook signature verification fails (400 response)

The GITEA_WEBHOOK_SECRET in your Codeveira .env does not match the Secret configured in the Gitea/Forgejo webhook settings. Both values must be identical. Update the secret on one side (either regenerate in .env and update the Gitea webhook, or delete and recreate the Gitea webhook using the existing .env value).

Only some pushes create code reviews

By default Codeveira creates a review for every push to every branch. If only some pushes create reviews, check the Branch filter setting in Codeveira → repository settings. A glob pattern like main would silently skip pushes to other branches. Clear the filter to match all branches, or adjust it to the branches you want to monitor.

Large diffs take a long time to appear

Codeveira fetches the diff asynchronously via a Sidekiq background job after receiving the webhook event. On a first push with many commits, or for commits with very large diffs, this may take a minute. The review page shows a loading indicator while the diff is being fetched. If the diff never appears, check the Sidekiq logs: docker compose logs worker.

Next: Bitbucket Integration → ← All docs