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 describes.
Before you start
- An installed instance that serves its host over HTTPS (Install on Kubernetes).
- An account on the GitLab instance that can create an OAuth application.
- The GitLab instance can reach
https://<host>/webhooks. kubectlwith access to the release namespace, andjq.- For a GitLab instance on a private network or with a private CA, follow 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
- On the GitLab instance, open Admin area → Applications, and add an application. Without the administrator role, use the Applications page of your user settings.
- Set Name to the name of your instance.
- Set Redirect URI to
https://<host>/api/login/oauth2/code/gitlab. - Select Confidential.
- Select the
read_userscope only. - Save the application.
- Copy the Application ID and the Secret.
Set the Helm values and Secret keys
-
Type the secret of the application. The shell does not show it:
read -rs GITLAB_OAUTH_CLIENT_SECRET && export GITLAB_OAUTH_CLIENT_SECRET -
Add the secret to the release Secret:
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 -
Add GitLab to
site.yaml:config: gitlab: enabled: true oauthClientId: 0123456789abcdef oauthBaseUrl: https://gitlab.example.com oauthDisplayName: Example GitLabValue What it sets Default config.gitlab.enabledGitLab workspaces, their sync, and repository checkout for practice reviews falseconfig.gitlab.oauthClientIdThe Application ID of the OAuth application Empty config.gitlab.oauthBaseUrlThe GitLab instance, for sign-in and for every GitLab workspace https://gitlab.comconfig.gitlab.oauthDisplayNameThe name on the sign-in button GitLab -
Apply
site.yaml. On a cluster, run thehelm upgradecommand of Install again. On one host, run the installer again (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 describes.
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
- Sign out of Hephaestus.
The sign-in page offers Continue with and your
oauthDisplayName. - Sign in with GitLab.
- 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). A change to a merge request then shows in the workspace without a wait for the scheduled sync.
Undo
- Set
config.gitlab.enabledtofalseinsite.yaml. - Apply
site.yaml. - Open Instance administration → Login providers.
- 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
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
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:
- In GitLab, open the group, or each project that the workspace monitored, then Settings → Webhooks.
- Delete the webhook whose URL contains
/webhooks/gitlab/connections/. - Release its block, as 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 describes:
- Send
GET https://<host>/api/workspaces/<slug>/connections, and note theidof the GitLab connection. - Send
PATCH https://<host>/api/workspaces/<slug>/connections/<id>/statuswith 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.syncCronsets it, hourly by default (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.