# Connect GitLab

Register the GitLab OAuth application, turn on GitLab in the Helm chart, and let workspace admins create GitLab workspaces.

Connect your GitLab instance so that people sign in with GitLab and workspace admins create GitLab workspaces.
An install connects one GitLab instance, gitlab.com or a self-managed one.
After this setup, a workspace admin creates the workspace in the web app, as [Set up your workspace](/user/workspace#create-a-workspace) describes.

## Before you start [#before-you-start]

- An installed instance that serves its host over HTTPS ([Install on Kubernetes](./kubernetes)).
- An account on the GitLab instance that can create an OAuth application.
- The GitLab instance can reach `https://<host>/webhooks`.
- `kubectl` with access to the release namespace, and `jq`.
- For a GitLab instance on a private network or with a private CA, follow [Private network](./private-network) first.

The commands use the release namespace `hephaestus` and the release Secret `hephaestus-app`.
Replace these names if your release uses other names.

## Register the GitLab OAuth application [#register-the-gitlab-oauth-application]

1. On the GitLab instance, open **Admin area → Applications**, and add an application.
   Without the administrator role, use the **Applications** page of your user settings.
2. Set **Name** to the name of your instance.
3. Set **Redirect URI** to `https://<host>/api/login/oauth2/code/gitlab`.
4. Select **Confidential**.
5. Select the `read_user` scope only.
6. Save the application.
7. Copy the **Application ID** and the **Secret**.

## Set the Helm values and Secret keys [#set-the-helm-values-and-secret-keys]

1. Type the secret of the application. The shell does not show it:

   ```bash
   read -rs GITLAB_OAUTH_CLIENT_SECRET && export GITLAB_OAUTH_CLIENT_SECRET
   ```

2. Add the secret to the release Secret:

   ```bash
   jq -n --arg secret "$GITLAB_OAUTH_CLIENT_SECRET" '{stringData: {GITLAB_OAUTH_CLIENT_SECRET: $secret}}' |
     kubectl -n hephaestus patch secret hephaestus-app --type merge --patch-file /dev/stdin
   ```

3. Add GitLab to `site.yaml`:

   ```yaml title="values.yaml"
   config:
     gitlab:
       enabled: true
       oauthClientId: 0123456789abcdef
       oauthBaseUrl: https://gitlab.example.com
       oauthDisplayName: Example GitLab
   ```

   | Value | What it sets | Default |
   | --- | --- | --- |
   | `config.gitlab.enabled` | GitLab workspaces, their sync, and repository checkout for practice reviews | `false` |
   | `config.gitlab.oauthClientId` | The **Application ID** of the OAuth application | Empty |
   | `config.gitlab.oauthBaseUrl` | The GitLab instance, for sign-in and for every GitLab workspace | `https://gitlab.com` |
   | `config.gitlab.oauthDisplayName` | The name on the sign-in button | `GitLab` |

4. Apply `site.yaml`.
   On a cluster, run the `helm upgrade` command of [Install](./kubernetes#install) again.
   On one host, run the installer again ([Run the installer](./k3s#2-run-the-installer)).

At its next start, the server creates the GitLab login provider if it does not exist.
After that, the server ignores the client ID and secret of the chart.
Change them under **Instance administration → Login providers**, as [Login provider secrets](./secret-custody#login-provider-secrets) describes.

## Token rotation [#token-rotation]

Hephaestus checks the token of each GitLab workspace daily and rotates it before it expires.
Only one server at a time checks the token of a workspace, and it holds no database transaction during GitLab calls.
A server that stops responding keeps that lock until its database connection closes, so no other server can rotate the token in the meantime.
The server stores a rotated token only if nobody paused, resumed or replaced the token during the call.
It discards a late answer after a token replacement, a pause or a resume.
The connection audit records an uncertain attempt as `GITLAB_TOKEN_ROTATION_UNCERTAIN`.

## Check that it worked [#check-that-it-worked]

1. Sign out of Hephaestus.
   The sign-in page offers **Continue with** and your `oauthDisplayName`.
2. Sign in with GitLab.
3. Open **Create workspace**.
   It offers **GitLab**.

After a workspace admin creates a GitLab workspace, open the group in GitLab, then **Settings → Webhooks**.
The list shows the webhook that Hephaestus registered.
On a GitLab without group webhooks, look in a monitored project instead ([GitLab without group webhooks](#gitlab-without-group-webhooks)).
A change to a merge request then shows in the workspace without a wait for the scheduled sync.

## Undo [#undo]

1. Set `config.gitlab.enabled` to `false` in `site.yaml`.
2. Apply `site.yaml`.
3. Open **Instance administration → Login providers**.
4. Select **Disable** for the GitLab provider.

GitLab workspaces then stop their sync, their practice reviews, and their feedback delivery.
Their synced work stays.

## GitLab instances and workspaces [#gitlab-instances-and-workspaces]

`config.gitlab.oauthBaseUrl` names the one GitLab instance of the install.
Hephaestus reads every GitLab project, member, and event from that instance, and it refuses a workspace on another instance.
An instance admin can add a login provider for another GitLab instance under **Instance administration → Login providers**.
That provider allows sign-in only, not workspaces.

For two GitLab instances, run one install for each instance, each with its own release name, database, and host.
The installs share no data, so each person has a separate account on each install.

A workspace admin creates a GitLab workspace with their own GitLab account on that instance.
Thus, they must sign in with GitLab, or link their GitLab account, before they create it.

## GitLab without group webhooks [#gitlab-without-group-webhooks]

Hephaestus registers a webhook on the GitLab group of each workspace, with a token that `WEBHOOK_ROUTING_SECRET` signs.
`hephaestus-keys.sh` generates that key, and you set nothing for it.
A group webhook needs the Owner role on the group, and a GitLab tier with group webhooks.
GitLab Community Edition and the Free tier have no group webhooks.

If GitLab refuses the group webhook, Hephaestus registers one webhook on each monitored project instead.
A project webhook needs the Maintainer role on the project, in every GitLab tier.
Hephaestus manages project webhooks as it manages the group webhook:

- A project that Hephaestus starts to monitor gets its webhook at the next sync.
- A project that Hephaestus no longer monitors loses its webhook at the next sync.
- A deleted project loses its webhook with it.
- A new routing key replaces every project webhook.
- Every 6 hours, Hephaestus replaces a project webhook that GitLab deleted or disabled.

A workspace removal does not remove the group webhook or the project webhooks at GitLab.
Hephaestus erases the access token first, so GitLab keeps the webhooks.
GitLab then sends events for the removed workspace, and Hephaestus does not store them.
Each webhook shows as a block under **Instance administration → Provider removals**, and its removal waits for authorization.
To remove a webhook after a workspace removal:

1. In GitLab, open the group, or each project that the workspace monitored, then **Settings → Webhooks**.
2. Delete the webhook whose URL contains `/webhooks/gitlab/connections/`.
3. Release its block, as [Provider removals](./instance-admin#provider-removals) describes.

**Administration → Integrations** has no **Disconnect** for GitLab yet.
A disconnect through the API removes every webhook of the connection, and keeps the workspace.
It erases the synced work of the connection, as a workspace removal does.
Afterwards, the GitLab page of the workspace offers **Reconnect GitLab**.
To disconnect, call the API as [Call the API](./instance-admin#call-the-api) describes:

1. Send `GET https://<host>/api/workspaces/<slug>/connections`, and note the `id` of the GitLab connection.
2. Send `PATCH https://<host>/api/workspaces/<slug>/connections/<id>/status` with the body `{"state": "UNINSTALLED"}`.

Project webhooks do not send member, subgroup, and project events.
Membership changes, new subgroups, and new projects show after the next sync.
A new project gets its webhook at that sync too.

To check the webhooks, open a monitored project in GitLab, then **Settings → Webhooks**.
The list shows the webhook that Hephaestus registered.

If GitLab refuses the group webhook and every project webhook, the GitLab page of the workspace shows **New work shows only after a sync**.
Workspace admins also get an email.
Hephaestus tries again every 6 hours, and clears the notice when a webhook works.
Until then, Hephaestus sees changes only when a sync runs:

- The scheduled sync reads new and changed work. `config.sync.syncCron` sets it, hourly by default ([Values](./helm-chart#values)).
- **Sync now** on the connection runs a sync at once.
- A person can request a review only of work that a sync has read.
- Feedback delivery does not need the webhook. Hephaestus posts its comments through the GitLab API.

To fix it, give the token the Owner role on the group, or the Maintainer role on each project.
Do not add a webhook yourself: Hephaestus accepts only the webhooks that it registers.

GitLab 18.6 or later sends the review state of each reviewer in merge request events.
On an earlier GitLab, approvals and change requests arrive only with the scheduled sync.