> ## Documentation Index
> Fetch the complete documentation index at: https://doc.entelligence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect self-managed GitLab

> Prepare a GitLab OAuth application, service user, access token, networking, and deployment-specific Entelligence onboarding.

Self-managed GitLab is not listed in the general **Connectors** catalog in the audited workspace. The currently documented Entelligence path uses a dedicated onboarding screen together with a GitLab OAuth application, a service user, and a personal access token.

## Before you begin

You need:

* A GitLab administrator
* An Entelligence workspace administrator
* A GitLab base URL reachable by Entelligence over an approved network path
* A TLS certificate trusted by the connecting systems
* A pilot group or project
* A dedicated GitLab service user
* An OAuth application and its client credentials
* A personal access token owned by the service user
* A credential owner and rotation date

Confirm that self-managed GitLab is enabled for the Entelligence deployment before creating credentials.

## 1. Obtain the Entelligence onboarding details

Ask the Entelligence workspace owner or [support@entelligence.ai](mailto:support@entelligence.ai) for:

* The self-managed GitLab onboarding or login URL
* The exact OAuth redirect URI
* The required OAuth application scopes
* The required personal access token scopes
* Any deployment-specific network or webhook requirements

<Warning>
  Do not look for this integration on **Connectors** and do not reuse a callback URI from another workspace or an old example. The redirect URI is an exact security boundary.
</Warning>

## 2. Create the GitLab OAuth application

In the application settings for the installed GitLab version:

1. Create a confidential application named **Entelligence** or another approved name.
2. Paste the exact redirect URI supplied for the deployment.
3. Select only the scopes required by the current Entelligence onboarding instructions.
4. Save the application.
5. Store the client ID and client secret in an approved secret manager.

GitLab navigation and available scopes vary by version. Use the documentation for the installed GitLab release rather than a generic menu path.

## 3. Create the service user and token

1. Create or designate a dedicated regular GitLab user for Entelligence.
2. Add the user only to the pilot groups or projects.
3. Record the user's numeric GitLab user ID.
4. While acting as that user, create a personal access token with the current Entelligence-required scopes.
5. Set an expiry that matches the organization's rotation policy.
6. Copy the token once and store it in the approved secret manager.

Do not apply OAuth-only identity scopes to the personal access token unless the GitLab token screen and current Entelligence instructions explicitly require and support them.

## 4. Configure network access

Confirm:

* Entelligence can resolve the GitLab hostname.
* HTTPS is reachable over the approved public or private route.
* Corporate proxy and TLS inspection are compatible.
* The GitLab certificate chain is trusted.
* The browser can complete the OAuth redirect to Entelligence.
* GitLab can deliver webhooks if the deployment uses them.
* Firewall and allowlist entries are documented.

Do not expose a private GitLab instance broadly merely to complete setup. Agree on the enterprise network path with Entelligence.

## 5. Complete the Entelligence onboarding form

1. Open the deployment-specific self-managed GitLab onboarding URL.
2. Enter the complete GitLab instance URL, including `https://`.
3. Search or continue to the connection form.
4. Enter the organization name, numeric service-user ID, and personal access token.
5. Supply the OAuth client ID and client secret only if the current form requests them; some flows can show an OAuth section as preconfigured.
6. Select **Connect GitLab**.
7. Wait for a successful redirect or connection confirmation.

After connection, open **Settings → Code Management** when that page is used by the deployment and synchronize the intended repositories.

## 6. Enable a pilot repository

1. Open **Code Review → Codebases**.
2. Find the synchronized pilot project.
3. Enable **PR Review** using the repository controls.
4. Open a non-draft test merge request.
5. Request or trigger a review using the configured workflow.
6. Verify Entelligence can read the change and post only the approved output.

## Verify

* The dedicated onboarding flow reports a successful connection.
* Only intended groups and projects synchronize.
* A normal Entelligence member cannot access an out-of-scope project.
* The test merge request is visible.
* A configured review can be posted.
* Revoking the OAuth application or personal access token stops future access.
* Reconnection restores only the approved scope.

## Rotate credentials

1. Inventory the OAuth application, service user, token, and webhook configuration.
2. Create the replacement during a change window.
3. Update the deployment-specific Entelligence connection.
4. Synchronize and run a read-only test.
5. Run one pilot review.
6. Revoke the old secret.
7. Record the next rotation date.

## Troubleshooting

| Symptom                  | Check                                                                             |
| ------------------------ | --------------------------------------------------------------------------------- |
| Invalid redirect URI     | Exact redirect URI supplied for this Entelligence deployment                      |
| Cannot reach instance    | DNS, approved route, firewall, proxy, TLS, and allowlist                          |
| Unauthorized             | Service-user ID, token, scope, expiry, and project membership                     |
| OAuth failure            | Client ID, client secret, confidential setting, redirect URI, and OAuth scopes    |
| Projects are missing     | GitLab group/project membership and Entelligence synchronization                  |
| Webhook is not delivered | Whether webhooks are required, URL, secret, network path, and GitLab delivery log |
| Review cannot post       | Service-user permission and protected-project policy                              |
| Login loops              | Cookie/session policy, redirect URI, base URL, and proxy headers                  |

Contact [support@entelligence.ai](mailto:support@entelligence.ai) with the GitLab version, deployment type, redacted error, timestamp, and request or delivery ID. Never send the client secret or token.