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.

For OpenHands Cloud, see GitLab Integration. 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.<your-base-domain>.
• The authentication service is reachable at https://auth.<your-base-domain> 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:

   https://<your-auth-hostname>/realms/allhands/broker/gitlab/endpoint
   

   Replace <your-auth-hostname> with your installation’s Authentication hostname (auth.<your-openhands-domain> by default), for example:

   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.

Store the client secret securely. Do not commit it to a repository.

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.

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.

The GitLab Host must be a bare hostname, for example gitlab.example.com. Do not include https://.

Standalone Helm

First, create a Kubernetes secret containing the GitLab OAuth credentials:

kubectl create secret generic gitlab-app -n openhands \
  --from-literal=client-id=<your-gitlab-client-id> \
  --from-literal=client-secret=<your-gitlab-client-secret>

Then set GitLab values in your site-values.yaml file:

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:

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.

Group webhooks require a GitLab Premium or Ultimate tier subscription. 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:

@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://<your-auth-hostname>/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
• Skills and Plugins
• GitLab Integration (Cloud)