GitLab Setup

This guide connects GitLab.com projects for merge-request reviews. For your own GitLab instance, use Self-Hosted GitLab Setup.

Prerequisites

You need a GitLab.com account, access to the projects, permission to create a Personal Access Token and sufficient project rights to manage webhooks. The active account and provider scope also apply when enabling repositories.

Setup Steps

Step 1: Sign In with GitLab OAuth

Choose GitLab on the Codity Platform sign-in page, authorize the connection and finish the welcome flow. Select your personal projects or the group account you intend to work in. GitLab OAuth signs you in; repository operations use the separately configured PAT.

Step 2: Create a Personal Access Token

In GitLab.com, open your profile's Access Tokens settings and create a personal access token using the scope-based token workflow. The current Codity token form lists api and read_user. api is needed for project API operations and webhook management; read-only API access is insufficient for creating webhooks. Choose an expiration allowed by your organization and copy the token after creation.

These are the scopes shown by the current integration. Do not treat read_repository and write_repository as two extra universally required scopes for this setup. GitLab distinguishes API access from Git-over-HTTP scopes; see its access-token scope reference and personal-token guide.

Step 3: Configure Token in Codity

  1. Open Repositories → Enable Repositories to reach GitLab Repositories (/gitlab-repos).
  2. Choose Configure token, or Update token if a token is already present. The token panel also appears when none is configured.
  3. Paste the PAT into Token, in the Personal access token panel.
  4. Select Validate token before saving if you want Codity to check it first.
  5. Choose Save token. On success, Codity loads the available repositories.

Validation confirms access through provider API calls. A valid identity alone does not prove the token's owner can create hooks on every project. Keep the token private; do not paste it into Help chat.

Step 4: Enable Repositories

On GitLab Repositories, find a project and choose Enable. Codity attempts to register its merge-request webhook. Check the enabled state and any error shown. Repeat for other projects. Disable stops the integration for that project.

The list is described as Projects available to your token. Token visibility and the currently selected account scope are distinct; seeing a project in a list does not override account or project authorization checks.

Step 5: Verify Setup

Return to Repositories and confirm the enabled project appears in the intended account. Open a small test MR targeting an allowed branch. Check for Codity review activity and completion. If no review starts, inspect GitLab Project Settings → Webhooks and recent deliveries, plus review triggers. Completion time varies.

Self-Hosted GitLab

Use the separate self-hosted sign-in and instance setup guide. Do not enter a self-hosted API URL into the GitLab.com token form.

Troubleshooting

No projects: check the PAT's expiration, scopes, project membership and the active account. Update the token in GitLab Repositories when needed.

Enable fails: read the returned error. Check the selected account and the PAT owner's permission to manage hooks on the project. Token scope does not grant project membership.

Reviews stop after token rotation: save the replacement PAT, then verify repository access and a test MR before revoking a still-needed credential.

Token Validates but Enable Fails

Token validation and enabling a project exercise different operations. A valid token can identify its owner and read projects while failing to create a project webhook.

  1. Confirm the project belongs to the intended personal/group account and that this scope is active in Codity.
  2. Check the PAT is current and has the scopes listed in the token form.
  3. Verify that the PAT owner can manage the relevant project's webhooks under its provider permissions and organization policy.
  4. Read the error from Enable and resolve the specific account or provider denial.
  5. Retry enabling, confirm its saved state and open an eligible test MR.

Adding scopes does not grant project membership. Likewise, selecting another Codity account does not change the PAT owner's GitLab permissions.

Enabled Project Receives No Review

Check effective automatic-review settings and target-branch scope first. Inspect the MR title, description and labels for supported opt-out markers. Then inspect the configured webhook and recent delivery results in the project's GitLab settings.

If events are delivered but no review completes, inspect the run's authorization, usage and service errors. Request @codity review in a separate MR comment if you need an explicit review; that command still requires access and usage availability.

Read Access Works but Posting Fails

Check the reported provider error for the feedback-writing operation. Verify the token is valid, its owner still belongs to the project and the integration has permission to perform the requested write. Autofix requires its own feature setting and applicable code-writing access; successful repository reads do not establish either.

For planned credential replacement, follow Token Rotation. Avoid pasting the token into an MR comment or a support request.

Best Practices

Use a token owner whose project access matches the intended account. Track expiration and recheck enabled projects after access changes.

Next Steps