Self-Hosted GitLab Setup

This guide covers connecting Codity to a self-hosted GitLab CE/EE instance, for both individual accounts and shared groups.

Self-hosted GitLab has its own sign-in path, separate from GitLab.com. If you use GitLab.com, follow GitLab Setup instead.

Prerequisites

• A GitLab CE/EE instance reachable from the internet over HTTPS with a valid certificate. If you use a private CA, see Private certificate authorities.
• An account on that instance with access to the projects you want reviewed
• Projects must allow webhook creation
• For group scope, you need to be an Owner of the group you want to administer

Two ways to sign in

Single sign-on takes about ten minutes to set up. After that everyone at your company signs in through a normal GitLab redirect and nobody pastes a token again.

Setting up single sign-on

You only do this once per instance.

Step 1: Create an OAuth Application in GitLab

1. In GitLab, go to Admin Area then Applications then New application. A non-admin can use User Settings then Applications instead, but an admin-owned application is what makes this work for everyone on the instance.
2. Fill it in:
   • Name: Codity SSO, or anything recognisable. Users see this name on the consent screen.
   • Redirect URI: https://dashboard-api.codity.ai/api/auth/gitlab-self-hosted/oauth/callback
   • Confidential: checked
   • Scopes: api and read_user
3. Click Save application.
4. Copy the Application ID and Secret. GitLab shows the secret only once.

Step 2: Register the application in Codity

1. In Codity, go to Settings then Self-Hosted GitLab.
2. Click Enable single sign-on for an instance.
3. Fill in:
   • Instance URL, for example https://gitlab.your-company.com
   • Application ID and Secret from Step 1
4. Save.

Codity marks the instance with a tick once the app is stored. That panel also shows the exact redirect URI to use, which is handy if your Codity deployment is not on dashboard-api.codity.ai.

Step 3: Sign in

1. On the Codity sign-in page, open the GitLab dropdown and choose Self-hosted GitLab.
2. Enter your instance URL and click Continue.
3. Because an application is registered, Codity skips the token field and sends you to your own GitLab.
4. Sign in to GitLab if you are not already, then click Authorize.
5. GitLab returns you to Codity, signed in.

Everyone else on that instance only needs Step 3.

Signing in with a Personal Access Token

Use this if you have not registered an OAuth Application.

Step 1: Create the token

1. In GitLab, go to User Settings then Access Tokens.
2. Give it these scopes:
   • api, which is required. Group discovery and merge request comments both need it.
   • read_user
   • read_repository
   • write_repository, only if you want Codity to commit fixes
3. Set an expiry you can live with, then copy the token.

Step 2: Sign in

1. On the sign-in page, choose Self-hosted GitLab.
2. Enter your instance URL and click Continue.
3. Paste the token into Personal / Project Access Token and click Sign in.

A Project Access Token also works, but it can only see its own project, so you get no group discovery.

Choosing a scope: individual or group

After signing in, Codity asks Which repositories? and gives you two options.

Individual (personal repositories)

Pick the entry named after your user. Codity then works with projects under your own namespace. Choose this if the instance has no groups, or you are evaluating Codity on your own.

Group repositories

Pick Group access, then choose a group. Codity lists every group you belong to, including subgroups. A subgroup shows up as its own entry, so you can pick acme-platform/backend separately from acme-platform.

The two scopes are separate accounts inside Codity. Each one keeps its own:

• enabled repositories
• seats and subscription
• teams
• policies

Switching scope later does not move anything between them, so pick the group if your projects live in one. That is what most companies want.

Enabling repositories

1. Go to Repositories and click Enable Repositories.
2. Codity lists the projects visible in your current scope, with the enabled count at the top.
3. Click Enable on each project you want reviewed.

Enabling a project registers a webhook on it pointing at https://ingress.codity.ai/api/webhook/gitlab, which is how GitLab tells Codity about merge requests. Disable removes that webhook again.

If you switch from personal to group scope, the list changes to that group's projects. Anything you enabled under the other scope stays enabled there.

Who can enable repositories

Enabling is an account admin action. In group scope that means you need an Analytics seat on the group, and Codity gives seat management to GitLab Owners of that group. If you are the first person setting up a group:

1. Go to Subscription.
2. Grant yourself the Analytics permission.
3. Go back to Repositories and enable your projects.

Without that you will see Only account admins can ... when you try to enable. Members below Owner cannot bootstrap a group on their own, so ask an Owner to grant them a seat first.

Checking that it works

1. Open a merge request in one of the enabled projects.
2. Within a minute Codity posts a comment saying the review has started.
3. The review itself follows, with a summary, workflow diagrams, inline findings and a security scan summary.

If nothing shows up, look at GitLab under Project, Settings, Webhooks, then Edit and Recent events. The response code there tells you whether GitLab reached Codity at all.

Network requirements

Codity connects out to your instance and your instance connects out to Codity, so both directions need to work.

• Your instance must be reachable from the internet over HTTPS.
• Your instance's External URL must match the hostname you gave Codity. If GitLab thinks it lives at a different address than the one actually serving it, webhook verification fails. Check it with sudo gitlab-rails runner "puts Gitlab.config.gitlab.url", and if it is wrong set external_url in /etc/gitlab/gitlab.rb and run sudo gitlab-ctl reconfigure.
• Your instance needs outbound access to ingress.codity.ai for webhooks.

Private certificate authorities

If your instance uses a certificate from a private CA, paste the CA certificate in PEM form under Add custom CA certificate on the sign-in page. This option only exists on the token path, so an instance behind a private CA needs the token flow rather than single sign-on.

Troubleshooting

"No self-hosted GitLab instance connected yet" on the repositories page

The connection is stored against the user who attached it. Sign in through the same instance, or reconnect it under Settings, Self-Hosted GitLab.

Only account admins can enable repositories

You are in group scope without an Analytics seat. See Who can enable repositories.

"No groups found"

Either the instance has no groups, or your token cannot see them. Group discovery needs the api scope, and a token with only read_api comes back empty. If the instance genuinely has no groups, continue with personal repositories.

Webhook deliveries return 401

The webhook's secret token no longer matches. Disable and re-enable the repository in Codity to register it again. Editing a webhook by hand in GitLab clears any field you do not resubmit, including the token.

"GitLab rejected that access token"

The token has expired, was revoked, or is missing the api scope. Create a new one and sign in again.

Reviews stop after working for a while

A Personal Access Token expired. This is the problem single sign-on removes, so consider setting it up.

Best practices

1. Register the OAuth Application early. It is a short job and it takes token rotation off everyone's plate.
2. Use group scope for company projects. Personal scope keeps its own seats, teams and policies, and moving later means enabling everything again.
3. Have an Owner do the initial group setup, so seats can be granted without needing a second person.
4. Keep External URL correct. Most self-hosted webhook problems turn out to be an address mismatch.
5. If you do use tokens, set a reminder before they expire. Reviews stop quietly otherwise.
6. Enable one or two projects first and confirm a review lands before rolling out more widely.

Next Steps

• GitLab.com setup if you also use hosted GitLab
• Managing seats
• Teams for organising reviewers within a group
• Policy checks to gate merges on review outcomes
• Code navigation