Skip to main content

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 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​

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.

    Credential Provider - Integrations tab

  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 https://gitlab.com, indicating that you're using a GitLab.com plan.

      See GitLab plans for more details.

    • Top Level Group ID: Enter the numerical top-level group ID that your service account belongs.

    • 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:

    Completed GitLab Service Account Credential Provider Integration

  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 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:

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

    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:

    {"id":12345678,"username":"<sa_name>","name":"<sa_name>","email":"<generated_value>"}

    Record the id as you'll need it in the next step.

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

  3. 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:

    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"

Additional resources​