> ## Documentation Index > Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt > Use this file to discover all available pages before exploring further. # GitLab > Configure GitLab authentication and repository webhooks for OpenHands Enterprise. This guide explains how to connect GitLab to a self-hosted OpenHands Enterprise installation. The integration lets users sign in with GitLab, open repositories, and invoke OpenHands from issue and merge request comments. > [!NOTE] > > For OpenHands Cloud, see [GitLab Integration](https://docs.openhands.dev/openhands/usage/cloud/gitlab-installation.md). > This page covers the OAuth application and resolver configuration for OpenHands Enterprise. ## Overview A self-hosted installation needs its own GitLab OAuth application so GitLab can send events to your domain. Setup has three parts: 1. Create a GitLab Application for the installation. 2. Enable GitLab in the OpenHands Enterprise configuration and deploy. 3. Have each user sign in to OpenHands with GitLab before they invoke `@openhands`. The integration uses the signed-in user's GitLab authorization for repository operations, including merge request comments and branch creation. OpenHands installs repository webhooks automatically so it can receive issue and merge request events. ## Prerequisites Before you start, confirm: * OpenHands Enterprise is reachable at `https://app.`. * The authentication service is reachable at `https://auth.` when using the default **Simple** hostname mode. * Both hostnames use publicly trusted TLS certificates. * You can create a GitLab Application under a GitLab Group or user account. * Users who will trigger OpenHands have access to the GitLab projects they want to use. * Network access from OpenHands to GitLab for API calls, and from GitLab back to the OpenHands app URL for webhook delivery. * If you are using self-managed GitLab with an internal or self-signed certificate, upload the issuing CA in the OpenHands Enterprise Admin Console under **Additional Trusted CA Certificates** before deploying. ## Step 1: Create a GitLab Application Create an OAuth application in GitLab so OpenHands can authenticate users and access repositories. 1. Go to your GitLab Group (or user account). 2. Navigate to **Settings > Applications**. 3. Set the **Redirect URI** to: ```text theme={null} https:///realms/allhands/broker/gitlab/endpoint ``` Replace `` with your installation's Authentication hostname (`auth.` by default), for example: ```text theme={null} https://auth.openhands.example.com/realms/allhands/broker/gitlab/endpoint ``` Replace only the hostname. Leave the rest of the path unchanged. 4. Select the following scopes: `api`, `read_user`, `write_repository`, `openid`, `email`, `profile`. 5. Save the application. 6. Note the **Client ID** and **Client Secret** provided by GitLab. > [!WARNING] > > Store the client secret securely. Do not commit it to a repository. > [!NOTE] > > The `api` scope is required so OpenHands can list repositories, install > webhooks, and post comments. The `write_repository` scope is required for Git > operations such as branch creation. ## Step 2: Configure OpenHands Enterprise Pick the path that matches how OpenHands Enterprise is deployed. > [tab] Replicated > > Open the Replicated Admin Console for your OpenHands Enterprise installation > and go to the application configuration page. > > In **GitLab Authentication**: > > 1. Enable **GitLab Authentication**. > > 2. Enter the **GitLab Host**. Leave it at `gitlab.com` for GitLab SaaS, or > enter the hostname of your self-managed GitLab instance. > > 3. Enter the **GitLab Client ID**. > > 4. Enter the **GitLab Client Secret**. > > 5. Save and deploy the updated configuration. > > > [!WARNING] > > > > The GitLab Host must be a bare hostname, for example > > `gitlab.example.com`. Do not include `https://`. > [tab] Standalone Helm > > First, create a Kubernetes secret containing the GitLab OAuth credentials: > > ```bash theme={null} > kubectl create secret generic gitlab-app -n openhands \ > --from-literal=client-id= \ > --from-literal=client-secret= > ``` > > Then set GitLab values in your `site-values.yaml` file: > > ```yaml theme={null} > gitlab: > enabled: true > # Host for self-hosted GitLab (e.g. gitlab.example.com). Defaults to gitlab.com. > host: "" > ``` > > Leave `host` empty for GitLab SaaS (`gitlab.com`). For self-managed GitLab, > set it to the bare hostname, for example `gitlab.example.com`. > > The `gitlab-app` Kubernetes secret provides the client ID and client secret. > When the chart is deployed, a job runs to configure the Keycloak realm with > the identity provider credentials you provided. > > Then redeploy the chart: > > ```bash theme={null} > helm upgrade --install openhands --namespace openhands \ > oci://ghcr.io/openhands/helm-charts/openhands -f site-values.yaml > ``` ## Step 3: Sign In with GitLab After the deployment is completed, users choose **Sign in with GitLab** on your app's login page. On first sign-in, users may be asked to accept OpenHands terms and complete an offline access flow. After sign-in, OpenHands stores the user's GitLab token so it can list repositories and run resolver jobs as that user. ## Install Repository Webhooks To trigger OpenHands on GitLab repositories, repository administrators can install the OpenHands webhook from **Settings > Integrations** within the OpenHands app. For each project or group that should support `@openhands` comments, click **Install**. If a webhook already exists, click **Reinstall** to refresh it. > [!NOTE] > > Group webhooks require a GitLab > [Premium or Ultimate tier subscription](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks). > For personal projects, project-level webhooks are used. OpenHands creates or updates a repository webhook that delivers issue and merge request events. The signing secret is generated and stored by OpenHands. ## Use the Built-In Resolver Mention `@openhands` in an issue, merge request comment, or inline merge request review comment. You can also add the `openhands` label to an issue. Include the task after the mention, for example: ```text theme={null} @openhands explain why this test is failing ``` The resolver starts a job only when: * The repository webhook is installed and active. * The mentioning GitLab user has signed in to OpenHands with GitLab. * The mentioning user has access to the repository. When a job starts, OpenHands: 1. Comments on the issue or merge request to let you know it is working on it, with a link to track progress. 2. Creates an OpenHands conversation with the issue or merge request context. 3. Runs the task using the triggering user's GitLab authorization. 4. For issues, opens a merge request if it determines that the issue has been resolved. 5. Comments with a summary of the performed tasks and a link to the conversation. ### Working with Issues On your repository, label an issue with `openhands` or add a message starting with `@openhands`. OpenHands will: 1. Comment on the issue to let you know it is working on it. 2. Open a merge request if it determines that the issue has been resolved. 3. Comment on the issue with a summary of the performed tasks and a link to the merge request. ### Working with Merge Requests To get OpenHands to work on merge requests, mention `@openhands` in the comments to: * Ask questions * Request updates * Get code explanations ## Troubleshooting | Symptom | Check | | - | - | | The GitLab login option is not visible | Confirm **GitLab Authentication** is enabled in the Admin Console or Helm values and the deployment has been applied. | | OAuth redirects fail | Confirm the redirect URI exactly matches `https:///realms/allhands/broker/gitlab/endpoint`. | | Login tries to reach an invalid `https://https://...` URL | Remove `https://` from the GitLab Host field in the Admin Console or Helm values. | | GitLab sign-in succeeds but no repositories are listed | Confirm the user has access to the GitLab projects and that the GitLab Host is correct for self-managed instances. | | `@openhands` is ignored | Confirm the webhook is installed for the repository, the sender has signed in to OpenHands with GitLab, and the sender has access to the repository. | | Webhook installation fails | Confirm the user has Admin or Owner permissions on the GitLab project or group and the OAuth application grants the `api` scope. | | GitLab webhook deliveries do not reach OpenHands | Confirm the GitLab instance can reach the OpenHands app URL and the TLS certificate is trusted. | | GitLab API calls fail with TLS errors | Upload the GitLab CA certificate in **Additional Trusted CA Certificates** and redeploy. | | OpenHands posts duplicate comments | Check whether more than one OpenHands webhook is installed for the repository. | ## Related Documentation * [Enterprise Quick Start](https://docs.openhands.dev/enterprise/quick-start.md) * [Skills and Plugins](https://docs.openhands.dev/enterprise/skills-and-plugins.md) * [GitLab Integration (Cloud)](https://docs.openhands.dev/openhands/usage/cloud/gitlab-installation.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.