Skip to main content
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:
    Replace <your-auth-hostname> with your installation’s Authentication hostname (auth.<your-openhands-domain> by default), for example:
    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.
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://.

​
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:
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