Service accounts

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

A service account is a type of machine user that is not tied to an individual human user.

A service account:

  • Does not use a licensed seat, but is not available on trial versions on GitLab.com. It is available on trial versions on GitLab self-managed.
  • Is not a:
    • Billable user.
    • Bot user.
  • Is listed in group membership as a service account.
  • Cannot sign in to GitLab through the UI.
  • Does not receive notification emails because it is a non-human account with an invalid email.

You should use service accounts in pipelines or integrations where credentials must be set up and maintained without being impacted by changes in human user membership.

You can authenticate as a service account with a personal access token. Service account users with a personal access token have the same abilities as a standard user. This includes interacting with registries and using the personal access token for Git operations.

Rate limits apply to service accounts:

Create a service account

The number of service accounts you can create is restricted by the number of service accounts allowed under your license:

  • On GitLab Free, service accounts are not available.
  • On GitLab Premium, you can create one service account for every paid seat you have.
  • On GitLab Ultimate, you can create an unlimited number of service accounts.

How you create an account differs depending on whether you are a:

  • Top-level group Owner.
  • In GitLab self-managed, an administrator.

Top-level group Owners

History
  • Introduced for GitLab.com in GitLab 16.3
  • Introduced in GitLab 17.5 with a feature flag named allow_top_level_group_owners_to_create_service_accounts for GitLab Self-Managed. Disabled by default.
  • Generally available in GitLab 17.6. Feature flag allow_top_level_group_owners_to_create_service_accounts removed.

Prerequisites:

  1. Create a service account.

    This service account is associated only with your top-level group.

  2. List all service account users.

  3. Create a personal access token for the service account user.

    You define the scopes for the service account by setting the scopes for the personal access token.

    Optional. You can create a personal access token with no expiry date.

    The response includes the personal access token value.

  4. Make this service account a group or project member by manually adding the service account user to the group or project.
  5. Use the returned personal access token value to authenticate as the service account user.

Administrators in GitLab self-managed

Offering: Self-managed

Prerequisites:

  • You must be an administrator for your self-managed instance.

  1. Create a service account.

    This service account is associated with the entire instance, not a specific group or project in the instance.

  2. List all service account users.

  3. Create a personal access token for the service account user.

    You define the scopes for the service account by setting the scopes for the personal access token.

    Optional. You can create a personal access token with no expiry date.

    The response includes the personal access token value.

  4. Make this service account a group or project member by manually adding the service account user to the group or project.
  5. Use the returned personal access token value to authenticate as the service account user.

Add a service account to subgroup or project

In terms of functionality, a service account is the same as an external user and has minimal access when you first create it.

You must manually add the service account to each project or group you want the account to have access to.

There is no limit to the number of service accounts you can add to a project or group.

A service account:

  • Can have different roles across multiple subgroups and projects of the same top-level group.
  • When created by a top-level group owner, only belongs to one top-level group.

Add to a subgroup or project

You can add the service account to a subgroup or project through the:

Change a service account role in a subgroup or project

You can change a service account role in a subgroup or project through the UI or the API.

To use the UI, go to the subgroup’s or project’s membership list and change the service account’s role.

To use the API, call the following endpoint: 

curl --request POST --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" \ --data "user_id=<service_account_user_id>&access_level=30" "https://gitlab.example.com/api/v4/projects/<project_id>/members"

For more information on the attributes, see the API documentation on editing a member of a group or project.

Rotate the personal access token

Prerequisites:

  • For service accounts created by top-level group Owners, you must have the Owner role in the top-level group or be an administrator.
  • For service accounts created by administrators, you must be an administrator for your self-managed instance.

Use the groups API to rotate the personal access token for a service account user.

Revoke a personal access token

Prerequisites:

  • You must be signed in as the service account user.

To revoke a personal access token, use the personal access tokens API. You can use either of the following methods:

Delete a service account

Top-Level Group Owners

Prerequisites:

  • You must have the Owner role in a top-level group.

To delete a service account, use the service accounts API to delete the service account user.

Administrators in GitLab self-managed

Prerequisites:

  • You must be an administrator for the instance the service account is associated with.

To delete a service account, use the users API to delete the service account user.

Disable a service account

Prerequisites:

  • You must have the Owner role for the group the service account is associated with.

If you are not an administrator for the instance or group a service account is associated with, you cannot directly delete that service account. Instead:

  1. Remove the service account as a member of all subgroups and projects: 

    curl --request DELETE --header "PRIVATE-TOKEN: <access_token_id>" "https://gitlab.example.com/api/v4/groups/<group_id>/members/<service_account_id>"

    For more information, see the API documentation on removing a member from a group or project.

Troubleshooting

“You are about to incur additional charges” warning when adding a service account

When you add a service account, you might see a warning message stating that this action will incur additional charges due to exceeding the subscription seat count. This behavior is being tracked in issue 433141.

Adding a service account does not:

  • Incur additional charges.
  • Increase your seat usage count after you’ve added the account.