How to Connect Gitea to VERDiiiCT: Step-by-Step Guide

Overview

VERDiiiCT integrates with Gitea through an SCM connection (authenticated with a Personal Access Token) and a webhook (which triggers reviews automatically when pull requests are opened or updated). Gitea's API is largely GitHub-compatible, so the setup process will feel familiar if you've used GitHub before.

Because Gitea is self-hosted, you'll need your instance's URL during setup.

The process takes about five minutes:

1. Create an Access Token in Gitea
2. Create an SCM connection in VERDiiiCT
3. Register a webhook for your repository
4. Configure the webhook in Gitea
5. Configure the webhook secret for payload verification

Prerequisites

• A VERDiiiCT account with Owner or Admin role in your organization
• A Gitea instance accessible over the internet (VERDiiiCT needs to receive webhook payloads and call the Gitea API)
• Admin access to the Gitea repository you want to connect

Step 1: Create an Access Token in Gitea

VERDiiiCT uses an access token to authenticate against the Gitea API — reading pull request diffs, fetching linked issues, and posting review comments.

1. In Gitea, click your profile avatar in the top-right corner and select Settings
2. Navigate to Applications

3. Under Manage Access Tokens, enter a token name: VERDiiiCT Code Review
4. Select the required permissions:
   • repository: Read and Write (to read PR diffs and post reviews)
   • issue: Read (to fetch linked issues for review context)

5. Click Generate Token and copy the token immediately — Gitea will not show it again

Security note: VERDiiiCT encrypts your token at rest using AES-256-GCM before saving it to the database. The plaintext token is never stored or logged.

Step 2: Create an SCM Connection in VERDiiiCT

An SCM connection links your Gitea instance to VERDiiiCT.

1. Log in to VERDiiiCT at app.verdiiict.com
2. Navigate to Connections in the sidebar
3. Click Add Connection

4. Fill in the connection details:
   • Provider: Select Gitea
   • Display Name: A friendly name like My Gitea Server
   • Organization URL: Your Gitea instance URL, e.g. https://gitea.example.com — this field is required for Gitea since it's self-hosted
   • Personal Access Token: Paste the token you created in Step 1
   • Webhook Secret (optional): You can leave this blank — VERDiiiCT generates a unique secret per webhook registration automatically

5. Click Create
6. Use the Test Connection button to verify VERDiiiCT can reach your Gitea instance and authenticate with your token

Important: Your Gitea instance must be accessible from the internet for VERDiiiCT to communicate with it. If your instance is behind a firewall, you'll need to allow inbound connections from VERDiiiCT's IP range and ensure VERDiiiCT can reach your Gitea API.

Step 3: Register a Webhook in VERDiiiCT

A webhook registration tells VERDiiiCT which repository to watch and generates a unique callback URL along with a secret token.

1. Open the connection you just created
2. Navigate to the Webhooks tab
3. Click Register Webhook

4. Fill in:

   • Repository ID: The numeric repository ID from Gitea (you can find this in the repository's API endpoint: https://gitea.example.com/api/v1/repos/{owner}/{repo} — the id field)
   • Repository Name: The repository name, e.g. my-api
   • Events (optional): Defaults to pull_request.created and pull_request.updated. Leave as default.

5. Click Register

VERDiiiCT returns a Webhook URL and generates a Secret Token. The webhook URL follows this format:

https://api.verdiiict.com/api/webhooks/gitea/{registration-id}

Important: Copy both the Webhook URL and the Secret Token. You will configure these in Gitea in the next step.

Step 4: Configure the Webhook in Gitea

1. In your Gitea repository, go to Settings → Webhooks
2. Click Add Webhook and select Gitea

3. Configure the webhook:
   • Target URL: Paste the Webhook URL from VERDiiiCT
   • HTTP Method: POST
   • Content Type: application/json
   • Secret: Paste the Secret Token from VERDiiiCT (the 64-character hex string)

4. Under Trigger On, select Custom Events
5. Check Pull Request and uncheck everything else

6. Ensure Active is checked
7. Click Add Webhook

You can test the webhook by clicking the Test Delivery button on the webhook detail page.

Step 5: How Secret Validation Works for Gitea

Gitea uses HMAC-SHA256 for webhook secret validation, similar to GitHub but with a key difference in the header format.

The Validation Flow

When Gitea sends a webhook payload, it:

1. Computes an HMAC-SHA256 hash of the entire request body using your secret token as the key
2. Sends the hash in the X-Gitea-Signature header as a raw hex string:

X-Gitea-Signature: a1b2c3d4e5f6...

Note the difference from GitHub: Gitea sends raw hex only (no sha256= prefix).

VERDiiiCT validates this by:

1. Reading the raw request body
2. Computing its own HMAC-SHA256 hash using the stored secret token
3. Comparing the computed hex hash against the value in the X-Gitea-Signature header
4. Using constant-time comparison to prevent timing attacks

// Simplified validation logic
var keyBytes = Encoding.UTF8.GetBytes(secretToken);
var bodyBytes = Encoding.UTF8.GetBytes(requestBody);
 
using var hmac = new HMACSHA256(keyBytes);
var hash = hmac.ComputeHash(bodyBytes);
var expected = Convert.ToHexString(hash).ToLowerInvariant();
 
// Constant-time comparison prevents timing attacks
CryptographicOperations.FixedTimeEquals(
    Encoding.UTF8.GetBytes(expected),
    Encoding.UTF8.GetBytes(signature));

Key Difference from GitHub

| Aspect | GitHub | Gitea | |--------|--------|-------| | Header | X-Hub-Signature-256 | X-Gitea-Signature | | Format | sha256=a1b2c3d4... | a1b2c3d4... (raw hex, no prefix) | | Algorithm | HMAC-SHA256 | HMAC-SHA256 |

The underlying cryptography is identical — only the header name and format differ.

Security best practice: Always configure the webhook secret. VERDiiiCT generates a cryptographically random 32-byte (64 hex character) token specifically for this purpose.

The Complete Flow

Once everything is configured, here's what happens automatically:

Developer opens or updates a Pull Request in Gitea
        ↓
Gitea fires the webhook (HTTP POST with HMAC signature)
        ↓
VERDiiiCT receives the payload at /api/webhooks/gitea/{id}
        ↓
VERDiiiCT validates the HMAC-SHA256 signature (X-Gitea-Signature)
        ↓
VERDiiiCT filters for relevant actions:
  - "opened" → new PR, triggers review
  - "synchronized" → new commits pushed, triggers review
  - Other actions → ignored
        ↓
VERDiiiCT fetches the PR diffs via Gitea API using the stored token
        ↓
AI (Claude or GPT) reviews the code changes
        ↓
VERDiiiCT posts a review with line-level comments and a verdict
(Approved / Needs Work / Rejected) directly on the PR

No manual steps required. Every pull request gets reviewed within minutes.

Troubleshooting

Webhook test returns an error

• Verify your Gitea instance is accessible from the internet
• Check that the webhook URL matches exactly what VERDiiiCT provided
• Confirm the webhook registration is still active in VERDiiiCT

Webhook returns 401

• The secret token doesn't match. Copy the exact secret from VERDiiiCT and paste it into the Gitea webhook's Secret field
• Make sure you're pasting the raw 64-character hex string

Webhook returns 200 but no review appears

• VERDiiiCT only processes opened and synchronized actions on pull request events. Other actions (labeled, closed, etc.) are accepted but ignored
• Check that your access token has the required permissions (repository Read/Write)
• Verify the token hasn't been revoked

VERDiiiCT can't reach your Gitea instance

• Ensure your Gitea instance has a valid SSL certificate (VERDiiiCT requires HTTPS)
• Check your firewall rules allow inbound connections from VERDiiiCT
• Verify the Organization URL in your connection settings is correct

Reviews don't post comments to the PR

• Ensure the access token has repository Write permissions
• Confirm the token belongs to a user with write access to the repository

Gitea-Specific Notes

Self-Hosted Considerations

Since Gitea is self-hosted, both your Gitea instance and VERDiiiCT need to be able to communicate:

• Gitea → VERDiiiCT: Webhook payloads sent when PRs are created/updated
• VERDiiiCT → Gitea: API calls to fetch diffs and post comments

If your Gitea instance is on a private network, consider using a reverse proxy or tunnel (like Cloudflare Tunnel) to expose the Gitea API securely.

Auth Header Difference

Gitea uses the token auth scheme instead of Bearer:

Authorization: token your-access-token

VERDiiiCT handles this automatically — you just need to provide the token when creating the connection.

What's Next

• How to Connect GitHub to VERDiiiCT — if you also use GitHub
• How to Connect Azure DevOps to VERDiiiCT — if you also use Azure DevOps
• Why Automated Code Reviews Matter — the case for AI-powered reviews