Skip to content

Commit 17862cc

Browse files
openhands-agentopenhands-agent
committed
Initial
1 parent 7c34815 commit 17862cc

3 files changed

Lines changed: 234 additions & 1 deletion

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -547,6 +547,7 @@
547547
"group": "Integrations",
548548
"pages": [
549549
"enterprise/integrations/github",
550+
"enterprise/integrations/gitlab",
550551
"enterprise/integrations/azure-devops",
551552
"enterprise/integrations/bitbucket-data-center",
552553
"enterprise/integrations/jira-cloud",

‎enterprise/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ agreements and API keys.
5656
OpenHands Enterprise integrates with your existing enterprise ecosystem:
5757

5858
- **Identity & Access**: Enterprise SAML/SSO for centralized authentication
59-
- **Source Control**: GitHub Enterprise, GitLab, [Azure Repos](/enterprise/integrations/azure-devops), and [Bitbucket Data Center](/enterprise/integrations/bitbucket-data-center)
59+
- **Source Control**: [GitHub Enterprise](/enterprise/integrations/github), [GitLab](/enterprise/integrations/gitlab), [Azure Repos](/enterprise/integrations/azure-devops), and [Bitbucket Data Center](/enterprise/integrations/bitbucket-data-center)
6060
- **Project Management**: Azure Boards through [Azure DevOps](/enterprise/integrations/azure-devops), [Jira Data Center](/enterprise/integrations/jira-data-center), and other ticketing systems
6161
- **Communication**: Slack integration for notifications and workflows
6262

‎enterprise/integrations/gitlab.mdx‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: GitLab
3+
description: Configure GitLab authentication and repository webhooks for OpenHands Enterprise.
4+
icon: code-branch
5+
---
6+
7+
This guide explains how to connect GitLab to a self-hosted OpenHands Enterprise
8+
installation. The integration lets users sign in with GitLab, open
9+
repositories, and invoke OpenHands from issue and merge request comments.
10+
11+
<Info>
12+
For OpenHands Cloud, see [GitLab Integration](/openhands/usage/cloud/gitlab-installation).
13+
This page covers the OAuth application and resolver configuration for OpenHands Enterprise.
14+
</Info>
15+
16+
## Overview
17+
18+
A self-hosted installation needs its own GitLab OAuth application so GitLab can
19+
send events to your domain. Setup has three parts:
20+
21+
1. Create a GitLab Application for the installation.
22+
2. Enable GitLab in the OpenHands Enterprise configuration and deploy.
23+
3. Have each user sign in to OpenHands with GitLab before they invoke `@openhands`.
24+
25+
The integration uses the signed-in user's GitLab authorization for repository
26+
operations, including merge request comments and branch creation. OpenHands
27+
installs repository webhooks automatically so it can receive issue and merge
28+
request events.
29+
30+
## Prerequisites
31+
32+
Before you start, confirm:
33+
34+
- OpenHands Enterprise is reachable at `https://app.<your-base-domain>`.
35+
- The authentication service is reachable at `https://auth.<your-base-domain>`
36+
when using the default **Simple** hostname mode.
37+
- Both hostnames use publicly trusted TLS certificates.
38+
- You can create a GitLab Application under a GitLab Group or user account.
39+
- Users who will trigger OpenHands have access to the GitLab projects they want
40+
to use.
41+
- Network access from OpenHands to GitLab for API calls, and from GitLab back to
42+
the OpenHands app URL for webhook delivery.
43+
- If you are using self-managed GitLab with an internal or self-signed
44+
certificate, upload the issuing CA in the OpenHands Enterprise Admin Console
45+
under **Additional Trusted CA Certificates** before deploying.
46+
47+
## Step 1: Create a GitLab Application
48+
49+
Create an OAuth application in GitLab so OpenHands can authenticate users and
50+
access repositories.
51+
52+
1. Go to your GitLab Group (or user account).
53+
2. Navigate to **Settings > Applications**.
54+
3. Set the **Redirect URI** to:
55+
56+
```text
57+
https://<your-auth-hostname>/realms/allhands/broker/gitlab/endpoint
58+
```
59+
60+
Replace `<your-auth-hostname>` with your installation's Authentication
61+
hostname (`auth.<your-openhands-domain>` by default), for example:
62+
63+
```text
64+
https://auth.openhands.example.com/realms/allhands/broker/gitlab/endpoint
65+
```
66+
67+
Replace only the hostname. Leave the rest of the path unchanged.
68+
69+
4. Select the following scopes: `api`, `read_user`, `write_repository`,
70+
`openid`, `email`, `profile`.
71+
5. Save the application.
72+
6. Note the **Client ID** and **Client Secret** provided by GitLab.
73+
74+
<Warning>
75+
Store the client secret securely. Do not commit it to a repository.
76+
</Warning>
77+
78+
<Note>
79+
The `api` scope is required so OpenHands can list repositories, install
80+
webhooks, and post comments. The `write_repository` scope is required for Git
81+
operations such as branch creation.
82+
</Note>
83+
84+
## Step 2: Configure OpenHands Enterprise
85+
86+
Pick the path that matches how OpenHands Enterprise is deployed.
87+
88+
<Tabs>
89+
<Tab title="Replicated">
90+
Open the Replicated Admin Console for your OpenHands Enterprise installation
91+
and go to the application configuration page.
92+
93+
In **GitLab Authentication**:
94+
95+
1. Enable **GitLab Authentication**.
96+
2. Enter the **GitLab Host**. Leave it at `gitlab.com` for GitLab SaaS, or
97+
enter the hostname of your self-managed GitLab instance.
98+
3. Enter the **GitLab Client ID**.
99+
4. Enter the **GitLab Client Secret**.
100+
5. Save and deploy the updated configuration.
101+
102+
<Warning>
103+
The GitLab Host must be a bare hostname, for example
104+
`gitlab.example.com`. Do not include `https://`.
105+
</Warning>
106+
</Tab>
107+
108+
<Tab title="Standalone Helm">
109+
First, create a Kubernetes secret containing the GitLab OAuth credentials:
110+
111+
```bash
112+
kubectl create secret generic gitlab-app -n openhands \
113+
--from-literal=client-id=<your-gitlab-client-id> \
114+
--from-literal=client-secret=<your-gitlab-client-secret>
115+
```
116+
117+
Then set GitLab values in your `site-values.yaml` file:
118+
119+
```yaml
120+
gitlab:
121+
enabled: true
122+
# Host for self-hosted GitLab (e.g. gitlab.example.com). Defaults to gitlab.com.
123+
host: ""
124+
```
125+
126+
Leave `host` empty for GitLab SaaS (`gitlab.com`). For self-managed GitLab,
127+
set it to the bare hostname, for example `gitlab.example.com`.
128+
129+
The `gitlab-app` Kubernetes secret provides the client ID and client secret.
130+
When the chart is deployed, a job runs to configure the Keycloak realm with
131+
the identity provider credentials you provided.
132+
133+
Then redeploy the chart:
134+
135+
```bash
136+
helm upgrade --install openhands --namespace openhands \
137+
oci://ghcr.io/openhands/helm-charts/openhands -f site-values.yaml
138+
```
139+
</Tab>
140+
</Tabs>
141+
142+
## Step 3: Sign In with GitLab
143+
144+
After the deployment is completed, users choose **Sign in with GitLab** on your
145+
app's login page.
146+
147+
On first sign-in, users may be asked to accept OpenHands terms and complete an
148+
offline access flow. After sign-in, OpenHands stores the user's GitLab token so
149+
it can list repositories and run resolver jobs as that user.
150+
151+
## Install Repository Webhooks
152+
153+
To trigger OpenHands on GitLab repositories, repository administrators can
154+
install the OpenHands webhook from **Settings > Integrations** within the
155+
OpenHands app. For each project or group that should support `@openhands`
156+
comments, click **Install**. If a webhook already exists, click **Reinstall** to
157+
refresh it.
158+
159+
<Note>
160+
Group webhooks require a GitLab
161+
[Premium or Ultimate tier subscription](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks).
162+
For personal projects, project-level webhooks are used.
163+
</Note>
164+
165+
OpenHands creates or updates a repository webhook that delivers issue and merge
166+
request events. The signing secret is generated and stored by OpenHands.
167+
168+
## Use the Built-In Resolver
169+
170+
Mention `@openhands` in an issue, merge request comment, or inline merge request
171+
review comment. You can also add the `openhands` label to an issue. Include the
172+
task after the mention, for example:
173+
174+
```text
175+
@openhands explain why this test is failing
176+
```
177+
178+
The resolver starts a job only when:
179+
180+
- The repository webhook is installed and active.
181+
- The mentioning GitLab user has signed in to OpenHands with GitLab.
182+
- The mentioning user has access to the repository.
183+
184+
When a job starts, OpenHands:
185+
186+
1. Comments on the issue or merge request to let you know it is working on it,
187+
with a link to track progress.
188+
2. Creates an OpenHands conversation with the issue or merge request context.
189+
3. Runs the task using the triggering user's GitLab authorization.
190+
4. For issues, opens a merge request if it determines that the issue has been
191+
resolved.
192+
5. Comments with a summary of the performed tasks and a link to the
193+
conversation.
194+
195+
### Working with Issues
196+
197+
On your repository, label an issue with `openhands` or add a message starting
198+
with `@openhands`. OpenHands will:
199+
200+
1. Comment on the issue to let you know it is working on it.
201+
2. Open a merge request if it determines that the issue has been resolved.
202+
3. Comment on the issue with a summary of the performed tasks and a link to the
203+
merge request.
204+
205+
### Working with Merge Requests
206+
207+
To get OpenHands to work on merge requests, mention `@openhands` in the comments
208+
to:
209+
210+
- Ask questions
211+
- Request updates
212+
- Get code explanations
213+
214+
## Troubleshooting
215+
216+
| Symptom | Check |
217+
|---|---|
218+
| 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. |
219+
| OAuth redirects fail | Confirm the redirect URI exactly matches `https://<your-auth-hostname>/realms/allhands/broker/gitlab/endpoint`. |
220+
| Login tries to reach an invalid `https://https://...` URL | Remove `https://` from the GitLab Host field in the Admin Console or Helm values. |
221+
| 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. |
222+
| `@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. |
223+
| 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. |
224+
| GitLab webhook deliveries do not reach OpenHands | Confirm the GitLab instance can reach the OpenHands app URL and the TLS certificate is trusted. |
225+
| GitLab API calls fail with TLS errors | Upload the GitLab CA certificate in **Additional Trusted CA Certificates** and redeploy. |
226+
| OpenHands posts duplicate comments | Check whether more than one OpenHands webhook is installed for the repository. |
227+
228+
## Related Documentation
229+
230+
- [Enterprise Quick Start](/enterprise/quick-start)
231+
- [Skills and Plugins](/enterprise/skills-and-plugins)
232+
- [GitLab Integration (Cloud)](/openhands/usage/cloud/gitlab-installation)

0 commit comments

Comments
 (0)