GitLab (Self-Managed)
Connect your own GitLab instance through an OAuth application you create on it: same proof, same repository pages, same scans as GitLab.com.
The GitLab (Self-Managed) integration connects your own GitLab instance to your mlab.sh organization. It works like GitLab (Cloud): you connect a group or your personal namespace, and every project you maintain in it is proven, scanned and kept in sync. The only difference is a one-time setup: mlab.sh cannot be pre-registered on your instance, so you create an OAuth application on it and give mlab.sh its credentials.
Requirements
- Any supported GitLab edition (Community or Enterprise).
- The instance must be reachable from the internet over https, on the default port (443), with a certificate from a public authority. mlab.sh reads your projects from its own infrastructure: an instance only reachable from your network or VPN cannot be connected.
- Its address must be the root of the instance (
https://gitlab.example.com, nothttps://example.com/gitlab). - You need the Owner role on the group that will own the application, or administrator access for an instance-wide application.
1. Create the application on your GitLab
Open Applications
On your GitLab, open the group that should own the application, then Settings → Applications. For an application shared by the whole instance, an administrator uses Admin → Applications instead.
Add a new application
| Field | Value |
|---|---|
| Name | mlab.sh (shown to your users when they authorize it) |
| Redirect URI | https://mlab.sh/orga/infra/gitlab/callback |
| Confidential | Checked |
| Scopes | read_api and read_repository, nothing else |
The redirect URI is also shown, with a copy button, on the setup page in mlab.sh.
Save and copy the credentials
Click Save application, then copy the Application ID and the Secret. GitLab shows the secret only once; if you lose it, use Renew secret and register the new one in mlab.sh.
2. Register it in mlab.sh
Open the setup page
In Organization → Infrastructure → Integrations, click Add an integration, then GitLab (Self-Managed).
Enter the instance and its application
Fill in the address of your GitLab, the Application ID and the Secret, then click Check and connect. mlab.sh checks that your instance is reachable and accepts the application before saving anything, and stores the secret encrypted.
Authorize and pick a namespace
You are sent to your GitLab to authorize mlab.sh, then back to mlab.sh to pick a group or your personal namespace, exactly as on GitLab.com.
Once registered, the instance is listed on the setup page with Connect a namespace: other members connect their groups from there without repeating the setup. Several instances can be registered.
How it behaves
Everything described for GitLab (Cloud) applies:
- a project is proven when the person who connected the namespace is Maintainer or Owner on it;
- namespaces are read again every day and pushes to default branches are noticed within minutes;
- repository pages show the Overview, Activity and Hygiene tabs, and code scans run on demand, on connect, on a schedule and on push;
- a namespace that loses its access offers Reconnect, and one unreachable for a week has its never-scanned projects removed (scanned ones are kept).
The repositories appear in your infrastructure under your instance's address, for example gitlab.example.com/platform/api.
Change or remove the application
- Renewed the secret? Register the instance again with the same address and the new secret: the existing connections keep working with it.
- Remove the instance: disconnect its namespaces from the Integrations page first, then use the remove button next to the instance on the setup page.
- Revoke on your side: deleting the application on your GitLab cuts mlab.sh's access at once; its namespaces then show Access lost.
Troubleshooting
| Message | What to do |
|---|---|
| Your GitLab must be reachable over https / on the default https port | Use the https address on port 443, at the root of the instance. |
| mlab.sh could not reach your GitLab | The instance is not reachable from the internet, its name does not resolve to a public address, or its certificate is not trusted. |
| Your GitLab does not recognise this Application ID and Secret | Copy both values again from Settings → Applications, or renew the secret. |
| That is GitLab.com | Use the GitLab (Cloud) integration instead. |
| GitLab says The redirect URI included is not valid | The application's redirect URI must be exactly https://mlab.sh/orga/infra/gitlab/callback. |
Data and privacy
mlab.sh reads your repositories on your instruction, in read-only mode, as a processor for your organization. GitLab is your provider, not a sub-processor of mlab.sh. What is read, what is kept and for how long is described in the privacy policy, the data processing agreement and the terms of service.
GitLab is a trademark of GitLab Inc. mlab.sh is not affiliated with, sponsored or endorsed by GitLab Inc.