Create a GitLab Service Account Integration for a GitLab.com plan"

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:

This integration requires the use of a top-level group GitLab account with the Owner role that performs the initial authorization for Aembit to start communicating with GitLab.

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

Prerequisites

Owner role access to GitLab Admin area and REST API
A GitLab Personal Access Token (PAT) for your GitLab service account with the Owner role as well as api and self-rotate scopes

Configure a GitLab service account integration

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

Log into your Aembit Tenant, and go to Credential Providers -> Integrations in the left sidebar.
(Optional) In the top right corner, select the Resource Set that you want this Credential Provider Integration to reside.
Click + New, which displays the Integration pop out menu.
Select GitLab Service Account.
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 https://gitlab.com, indicating that you’re using a GitLab.com plan.
  
  See GitLab subscriptions for more details.
- Personal Access Token: Enter the GitLab Personal Access Token that’s associated with your service account owned by a top-level group which 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:
Click Save.

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

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 and PAT

The service account you use for the GitLab Server Account integration must be owned by a top-level group access to GitLab APIs.

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

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 <top_level_group_id> with your numeric top-level group ID. For name and username, you can use the same value for both or follow whatever method you desire.
Terminal window
```
curl --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
  -X POST "https://gitlab.com/api/v4/groups/<top_level_group_id>/service_accounts" \
  --data "name=<sa_name>" \
  --data "username=<sa_username>"
```
If successful, the response should look similar to the following:
Terminal window
```
{"id":12345678,"username":"<sa_name>","name":"<sa_name>","email":"<generated_value>"}
```
Record the id as you’ll need it in the next step.

Create a PAT for the GitLab service account you just created.

Make sure to replace <GITLAB_TOKEN> with your GitLab API access token, <top_level_group_id> with your numeric top-level group ID, and <service_account_user_id> with the user_id you recorded from the previous step:

curl --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
  -X POST "https://gitlab.com/api/v4/groups/<top_level_group_id>/service_accounts/<service_account_user_id>/personal_access_tokens" \
  --data "name=<sa_username>" \
  --data "scopes[]=api,self_rotate"

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":<service_account_user_id>,"last_used_at":null,"active":true,"expires_at":"2025-03-31","token":"<token>"}

Record the token value as you’ll need it in the final step.

Add the new service account you just created to your top-level group:

Make sure to replace <GITLAB_TOKEN> with your GitLab API access token and <service_account_user_id> with the user_id you recorded earlier:
Terminal window
```
curl --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
  -X POST "https://gitlab.com/api/v4/groups/84110211/members" \
  --data "user_id=<service_account_user_id>" \
  --data "access_level=50"
```