Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

GitLab Server - Fine-grained token

Data Access by Hivel

  • Hivel accesses the past 60-90 days of commits and pull requests from active repositories during the initial sync.

Authorization Mechanism

  • Hivel employs GitLab Server's personal access token for authentication.

  • Users maintain full control and can withdraw access by revoking the Personal Access Token.

Effortlessly Connect Your GitLab Server with Hivel

This easy-to-follow guide will lead you through each step, ensuring a smooth and efficient integration process to unlock efficiency insights across your org.

Step 1: Gather Your GitLab Server Details

First things first, let's get some essential information from your GitLab Server:

  • GitLab Server URL: This is your gateway to accessing your GitLab Server. Look for an address in the format of https://{your-git-domain}.com/. Don't forget to replace {your-git-domain} with your actual domain.

  • GitLab Server Version: Compatibility is key, and knowing your GitLab Server version is crucial. Here's how to find it:

    • Head over to your GitLab Server interface.

    • Click on the 'Help' section. It’s usually at the end of your GitLab URL, like this: /help.

    • You'll see your version info displayed, typically in the format of "GitLab Community Edition {x.x.x} / GitLab Enterprise Edition {x.x.x}".

Step 2: Whitelist Necessary IP Addresses

For a secure and uninterrupted connection, make sure to whitelist the following IP addresses:

  • Mandatory IPs:

    • 107.23.139.76

    • 3.219.89.23

  • Recommended but Optional IPs:

    • 45.119.114.218

    • 183.82.116.218

Step 3: Prepare a Service Account

  1. Log into the GitLab service account:

    • Use a dedicated service account that has access to the required repositories for Hivel integration.

    • Avoid using personal GitLab accounts to ensure only the intended repositories are accessed.

Step 4: Open Access Tokens

  1. In your GitLab account, click your avatar in the top-right corner.

  2. Select Preferences.

  1. On the left sidebar, select Access > Personal access tokens.

Step 5: Click on the Generate token dropdown and select Fine-grained token.

Step 6: Configure the Fine-Grained Personal Access Token

  1. Enter a name (e.g. Hivel), description and set the longest expiry date your organization's policy allows. (GitLab requires an expiry date on personal access tokens. You can revoke the token manually when the engagement ends.)

  2. Under Group and project access, choose between the following three options, based on what you've agreed to share with Hivel per your organization's data-sharing policy:

  1. Grant permissions using the Resource and permission selector. It has three tabs: Group and project, User, and Global. Within a tab, the left panel lists resource categories (e.g. Projects, Repository, Groups). Each category row has a ‘›’ arrow - click it to expand the category and reveal its specific sub-permissions as checkboxes underneath. Checking one adds a row for it to the panel on the right.

None of these rows default to Read. After adding a permission, you must open its dropdown on the right-hand table and explicitly set it to Read.

Worked example - selecting Project (Group and project tab):

  1. On the Group and project tab, find Projects in the left panel.

  2. Click the ‘›’ arrow next to Projects to expand it.

  3. Check Project in the list that appears.

  1. A Project row is added to the panel on the right. Open its dropdown in the right panel and set the “Select permissions” to Read.

Repeat this same expand → check → set-to-Read pattern for every permission below. Where a category needs more than one sub-permission (e.g. Repository), expand it once and check all of them before moving to the next category.

Group and project tab:

  • Groups → check Group

  • Projects → check Project

  • Project Planning → check Work Item

  • Repository → check Branch, Commit, Merge Request, Repository

  • System Access → check Member

User tab:

  • Groups → check Group

  • Projects → check Project

  • System Access → check Personal Access Token

Global tab:

  • System Access → check Metadata

Note: By default, no permission is selected at all. Before moving on, go back through every item in the three lists above and cross-check two things for each: (1) it's actually checked in the left panel, and (2) its row on the right is explicitly set to Read. Any permission you skip, or leave unset, is simply left out of the token entirely - the connection may still work, but whatever that permission covers will be missing or fail for Hivel.

Once every permission above has been cross-checked and set to Read, continue to the next step.

Step 7: Connect in Hivel

  1. Copy the generated token immediately, as you won't be able to view it again.

  2. Submit: a. GitLab token b. Email c. base URL

    Obtaining base URL:

    Open your GitLab dashboard or any project page and copy only the base URL from your browser’s address bar, excluding the project name and anything that follows it (e.g., https://company.com). For detailed instructions, How to Find Your GitLab Server URL?

    d. username to Hivel.

Hivel validates the token instantly - if the token is wrong, expired, or missing any of the required permissions, Hivel shows a clear message telling you exactly what the problem is. Generate a new token with the correct permissions and reconnect.

That's it, all done!

Continue setting up your integrations

Now that GitLab Server is connected, connect the rest of your on-prem tools to complete your setup - Back to Integrations.

PreviousGitLab Server - Legacy token (recommended)
NextHow to Find Your GitLab Server URL?

Last updated