Codeveira› Docs› GitLab Integration

GitLab Integration

Connect Codeveira to GitLab — whether you use GitLab.com or a self-hosted instance. This guide walks through creating an access token, adding your first repository, configuring a webhook for automatic code reviews, and optionally enabling OAuth single sign-on.

Prerequisites

How Codeveira integrates with GitLab

Codeveira connects to GitLab in two complementary ways: a read-only API connection to fetch commit data, and a webhook to receive push notifications in real time.

Read-only API access

The personal access token you create in Step 1 gives Codeveira access to the GitLab REST API v4. Every API call Codeveira makes is read-only — it never pushes to branches, creates merge requests, modifies labels, or changes anything in your GitLab project. Specifically, Codeveira uses the API to:

The api scope is the minimum scope that covers all these read operations across both GitLab.com and self-hosted instances. If GitLab introduces a finer-grained read_repository scope for all endpoints Codeveira needs, a future release will document the narrower scope.

Automatic review creation via webhooks

The webhook you configure in Step 3 tells GitLab to send an HTTP POST to /webhooks/gitlab on every push. When Codeveira receives a valid push event it:

  1. Verifies the HMAC signature using the X-Gitlab-Token header against your WEBHOOK_SECRET
  2. Extracts the list of commits from the push payload
  3. Groups commits by author (consecutive commits by the same author are grouped into one review)
  4. Creates a code review for each group and fetches the full diff via the API
  5. Sends email notifications to any assigned reviewers
  6. Triggers the AI reviewer bot (if one is configured for this repository) to analyze the diff and post inline comments
Webhooks are optional. Without a webhook you can still manually browse commits on the Codeveira repository page and click Create review. Webhooks simply make this happen automatically on every push, without any manual action.

Branch filtering

By default Codeveira creates a review for every push to every branch. You can limit this in Codeveira → repository settings → Branch filter — enter a glob pattern such as main or release/* and only pushes to matching branches will create reviews.

1

Create a GitLab access token

Codeveira uses a GitLab personal access token to fetch commits and diffs via the GitLab API.

  1. Sign in to GitLab and click your avatar in the top-right corner
  2. Choose Edit profile
  3. In the left sidebar, click Access tokens
  4. Click Add new token
  5. Fill in the fields:
    • Token name: Codeveira
    • Expiration date: choose a date that suits your rotation policy
    • Select scopes: check api
  6. Click Create personal access token
  7. Copy the token — it is shown only once
Keep the token safe — it grants full API access to your GitLab account. Store it in your password manager and never commit it to version control.
2

Add the repository in Codeveira

In Codeveira, go to Repositories → New Repository and click the GitLab button at the top of the form. Fill in the following fields:

  • Name — display name for the repository inside Codeveira
  • GitLab Project ID — found in your GitLab project under Settings → General (shown at the top as "Project ID")
  • GitLab Path — the namespace and project slug, e.g. mygroup/myrepo
  • GitLab URL — base URL of your GitLab instance, e.g. https://gitlab.example.com. Optional if the GITLAB_URL environment variable is already set in your .env
  • Access Token — the personal access token you created in Step 1
For self-hosted GitLab, always set the GitLab URL field — it overrides the GITLAB_URL environment variable for this repository only, which is useful when you connect repositories from multiple GitLab instances.

Click Save. Codeveira will immediately test the connection by fetching the project metadata. If the token or project ID is wrong you will see an error at this point.

3

Configure the webhook

A webhook tells GitLab to notify Codeveira on every push so that code reviews are created automatically.

  1. In your GitLab project, go to Settings → Webhooks
  2. Click Add new webhook
  3. Set the URL to: 
    https://codeveira.yourdomain.com/webhooks/gitlab
  4. Set the Secret token to the value of WEBHOOK_SECRET from your .env file
  5. Under Trigger, check Push events only
  6. Enable SSL verification if your Codeveira instance is served over HTTPS (recommended)
  7. Click Add webhook
Webhooks create code reviews automatically on every push. Without a webhook you can still trigger reviews manually from the Codeveira dashboard — webhooks just make it hands-free.
4

OAuth login (optional)

Enabling OAuth lets your team sign in to Codeveira with their GitLab credentials using the Sign in with GitLab button — no separate password required.

  1. In GitLab, go to Admin area → Applications → New application (requires GitLab admin rights)
  2. Fill in:
    • Name: Codeveira
    • Redirect URI: https://codeveira.yourdomain.com/users/auth/gitlab/callback
    • Scopes: check read_user and openid
  3. Click Save application
  4. Copy the Application ID and the Secret
  5. Add them to your .env: 
    GITLAB_APP_ID=your_application_id
GITLAB_APP_SECRET=your_application_secret
  6. Restart Codeveira: 
    docker compose restart app

The Sign in with GitLab button will appear on the login page after the restart.

Troubleshooting

"401 Unauthorized"

The token is expired or was created with the wrong scope. Re-create the token in GitLab → Access tokens and make sure the api scope is checked. Update the token in Codeveira → repository settings.

"Project not found"

Either the GitLab Project ID is wrong, or the token belongs to a user who does not have access to that project. Verify the project ID in GitLab → Settings → General. Check membership under GitLab → project → Settings → Members.

Webhook not triggering

Check GitLab → Settings → Webhooks → Recent deliveries for the failed request and its response code. Common causes:

← Installation Next: GitHub Integration →