Create a GitLab Service Account Integration for a Dedicated/Self-Managed instance

The GitLab service account Credential Provider Integration allows you to create a Managed GitLab Account Credential Provider, which provides credential lifecycle management and rotation capabilities for secure authentication between your GitLab instances and other Client Workloads. This page details everything you need to create a GitLab Service Account Credential Provider Integration.

This integration requires the use of two types of GitLab accounts:

• A GitLab administrator account that performs the initial authorization for Aembit to start communicating with GitLab.

• A GitLab service account that performs credential lifecycle management for the Managed GitLab Account Credential Provider.

See How the GitLab Service Account integration works for more details.

Prerequisites

• Administrator access to GitLab Admin area and the GitLab REST API

• A GitLab Personal Access Token (PAT) for your GitLab service account with api and self-rotate scopes

• The URL of your GitLab Dedicated or GitLab Self-Managed instance (see GitLab’s plans for details)
  For example: gitlab_tenant_name.gitlab-dedicated.com or https://gitlab.my-company.com

Configure a GitLab service account integration

To create a GitLab service account integration, follow these steps:

1. Log into your Aembit Tenant, and go to Credential Providers -> Integrations in the left sidebar.

   

2. (Optional) In the top right corner, select the Resource Set that you want this Credential Provider Integration to reside.

3. Click + New, which displays the Integration pop out menu.

4. Select GitLab Service Account.

5. Fill out the following fields on the GitLab Service Account form:

   • Display Name: Enter a unique name for this integration.

   • Description: (Optional) Enter a description.

   • Token Endpoint URL: Enter the URL of your GitLab Dedicated or GitLab Self-Managed instance.

     See GitLab subscriptions for more details.

   • Top Level Group ID: n/a
     Aembit disables this field when using GitLab Dedicated or Self-Managed instance URLs.

   • Personal Access Token: Enter the GitLab Personal Access Token that’s associated with your instance-level administrator service account that must have api and self-rotate scopes.

     If you don’t already have a GitLab service account with a PAT, see Create a GitLab service account and PAT.

   The form should look similar to the following screenshot:

   

6. Click Save.

   Aembit displays the new integration in the list of Credential Provider Integrations.

   Note

   As soon as you successfully create the integration, Aembit rotates the token for the GitLab service account and regularly rotates it as long as the Credential Provider Integration exists.

Create a GitLab service account PAT

To create a GitLab service account PAT, you must have Administrator access to your GitLab Admin area and GitLab APIs.

This process has two main parts:

1. Create a PAT for your GitLab administrator account using the GitLab UI.

2. Create a GitLab service account and PAT using both the GitLab API and GitLab UI.

Create a GitLab administrator account PAT

To create a PAT for your GitLab administrator account, follow these steps:

1. Log into your GitLab Admin area with an administrator user account.

2. See Create a personal access token in the GitLab docs to create a PAT for your administrator user account (not the service account).

3. Keep the GitLab Admin area UI open, as you need it in the next step.

Create a GitLab service account and PAT

To create a GitLab service account and PAT, follow these steps:

Note

GitLab doesn’t provide a way to create service accounts from the Admin area UI, so you must use the API to create the service account. See GitLab issue #509870 for more details.

1. From your terminal, enter the following command to create the GitLab service account you want to associate with the integration. Make sure to replace <GITLAB_TOKEN> with your GitLab API access token and <GITLAB_URL> with your GitLab instance URL. For <name> and <username>, you can use the same value for both or follow whatever method you desire.

   curl --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
     -X POST "<GITLAB_URL>/api/v4/service_accounts" \
     --data "name=<sa_name>" \
     --data "username=<sa_username>"

2. From your GitLab Admin area, go to to Admin area -> Users and select the service account you just created.

3. Go to Access Level, and change the Access Level from Regular to Administrator.

4. Back in your terminal, create a PAT for the GitLab service account you just made Administrator.

   Make sure to replace <GITLAB_TOKEN> with your GitLab API access token, <GITLAB_URL> with your GitLab instance URL, and <token_name> with the same value you used to create the service account:

   curl --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
     -X POST "<GITLAB_URL>/api/v4/users/<user_ID>/personal_access_tokens" \
     --data "scopes[]=api,self_rotate" \
     --data "name=<token_name>"

   If successful, the response should look similar to the following:

   {"id":1234,"name":"token_name","revoked":false,"created_at":"2025-03-21T20:18:23.333Z","description":null,"scopes":["api","self_rotate"],"user_id":36,"last_used_at":null,"active":true,"expires_at":"2025-03-31","token":"your_token"}

5. Record the <token> value in the response and use it as the Personal Access Token in the Configure a GitLab service account integration section.

Additional resources

• Managed GitLab Account
• Credential Provider Integrations overview
• GitLab.com integration