Workforce Intelligence

Connect to GitLab

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.

  1. 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)

  2. In GitLab, go to Admin Area > Applications and create a new application.

  3. Set the Redirect URL to the value shown in the Workforce Intelligence dialog. It must match exactly.

  4. Select the api scope. Workforce Intelligence uses only this scope.

  5. Mark the application as Trusted and Confidential.

  6. 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.

  1. Open the Workforce Intelligence dialog. It lists the Workforce Intelligence egress IP addresses, one per line, with a Copy button.

  2. 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 https://. Don't include a username or password in the URL.

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 my-group/my-subgroup. This includes its subgroups. Leave it empty to include every project you can access.

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 Host, Content-Length, Transfer-Encoding, or Connection.

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:

  1. Go to Settings | Connectors.

  2. 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 my-group/my-subgroup.

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.