Teams that build in a self-hosted GitLab and plan their work in Jira can connect GitLab to Workforce Intelligence to match their commits and merge requests to Jira work and AI spend.
Workforce Intelligence supports self-hosted GitLab only. GitLab.com is not supported.
Connecting to GitLab
Before You Start
Make sure your setup meets these requirements:
-
GitLab version 16 or later, reachable over HTTPS.
-
A certificate from a public certificate authority. Self-signed certificates and certificates from a private internal CA won't work.
-
A public hostname. The address must resolve to a public IP. Private, loopback, and link-local addresses are refused.
-
One GitLab server per Workforce Intelligence account. If you already have a GitLab server connected and want to switch, disconnect the current connection first.
You'll also need:
-
An administrator account on GitLab, or a user with the Maintainer role (or higher) on the projects you want to connect. If you connect a group, the Maintainer role is needed on that group.
Step 1: Create an OAuth application in GitLab
An OAuth application is how Workforce Intelligence gets permission to access your GitLab projects. You create it in GitLab's Admin Area.
-
In Workforce Intelligence, open the GitLab connector and select Connect. Keep this dialog open. It shows two values you'll need:
-
The redirect URL
-
The IP addresses Workforce Intelligence connects from (see Step 2)
-
-
In GitLab, go to Admin Area > Applications and create a new application.
-
Set the Redirect URL to the value shown in the Workforce Intelligence dialog. It must match exactly.
-
Select the api scope. Workforce Intelligence uses only this scope.
-
Mark the application as Trusted and Confidential.
-
Save the application. Then copy the Application ID and Secret.
GitLab shows the secret only once, so keep it somewhere safe until you've entered it in Workforce Intelligence.
Step 2: Allow Workforce Intelligence Through Your Firewall
If your GitLab server is behind a firewall, proxy, or gateway, ensure Workforce Intelligence can reach it.
-
Open the Workforce Intelligence dialog. It lists the Workforce Intelligence egress IP addresses, one per line, with a Copy button.
-
Add those addresses to your allowlist for HTTPS traffic to GitLab.
Workforce Intelligence also needs to receive webhooks from GitLab. The Workforce Intelligence dialog shows the webhook host. Make sure GitLab can send HTTPS requests to that host.
Step 3: Register the Connection in Workforce Intelligence
Back in the Workforce Intelligence dialog, on the Register screen, fill in the following fields:
|
Field |
Required |
What to enter |
|---|---|---|
|
GitLab address |
Yes |
Your server's address, starting with |
|
Application ID and Secret |
Yes |
The values you copied from GitLab. Workforce Intelligence stores the secret in an encrypted form and never displays it again. |
|
Group path |
No |
A group to limit Workforce Intelligence to, such as |
|
Custom headers |
No |
Extra headers Workforce Intelligence sends with every request to GitLab. You can add up to 10. Each name must be unique, and no value can be blank. Workforce Intelligence stores them encrypted and never displays them again. You can't use |
Custom headers are only needed if your GitLab server sits behind a gateway that requires them. Most setups don't need any.
Step 4: Test the Connection
On the Test screen, select Test connection. Workforce Intelligence checks three things:
-
The address is reachable.
-
The server is GitLab.
-
The application ID and secret are valid.
If the test fails, see the troubleshooting table below.
Step 5: Authorize Workforce Intelligence
On the Authorize screen, select Authorize. You'll be sent to GitLab to sign in. Sign in as the user who should authorize the connection (an administrator, or a user with the right role), then approve the request.
The authorization link expires after 10 minutes. If it expires, select Authorize again.
What Happens After You Connect?
-
Workforce Intelligence sets up webhooks on every project it can access, so GitLab can notify Workforce Intelligence when something changes.
-
Workforce Intelligence imports the last 90 days of commits, merge requests, approvals, and comments.
-
Projects where the authorizing user doesn't have the Maintainer role are listed, but without a webhook. Workforce Intelligence can't create webhooks on those projects.
-
Projects without a webhook are retried every hour. The connector card shows a Webhooks missing badge with the count.
-
Workforce Intelligence refreshes its access automatically. If GitLab stops accepting that access, the connector card asks you to reauthorize.
Disconnecting GitLab
To disconnect GitLab from Workforce Intelligence:
-
Go to Settings | Connectors.
-
Locate the GitLab connector and select Disconnect.
Workforce Intelligence will remove its webhooks from your GitLab projects and delete the stored credentials. Data Workforce Intelligence has already imported will remain in Workforce Intelligence.
Troubleshooting
If you encounter an error when connecting to GitLab, refer to the table below for troubleshooting.
|
Message |
What to do |
|---|---|
|
Could not resolve the host name |
Check that the address uses a public hostname that DNS can resolve. |
|
Could not reach your GitLab server |
Allow Workforce Intelligence's IP addresses through your firewall, proxy, or gateway. |
|
Address is not allowed |
Use a public address. Private and local addresses aren't supported. |
|
Certificate not trusted by a public certificate authority |
Install a certificate from a public certificate authority. |
|
Did not answer like a GitLab server |
Check the URL. If you use a gateway, check any headers it requires. |
|
GitLab rejected the application ID or secret |
Copy both values again from GitLab. |
|
GitLab did not approve the request |
Make sure the redirect URL in GitLab matches the one in Workforce Intelligence exactly. |
|
Application needs the api scope |
In GitLab, add the api scope to the application. |
|
Version not supported |
Upgrade GitLab to version 16 or later. |
|
Group path not found |
Enter the full group path, such as |
|
Needs the Maintainer role or higher |
Authorize as an administrator, or ask an administrator to give you the Maintainer role. |
|
No accessible projects |
Check the group path, and confirm the authorizing user has access to the projects. |
|
Authorization link expired or already used |
Select Authorize again to get a new link. |
|
A GitLab server is already connected |
Disconnect the existing server first. |