Service accounts

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 unless the email address is set to a valid address.

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:

• On GitLab.com, there are GitLab.com-specific rate limits.
• On GitLab Self-Managed and GitLab Dedicated, there are both:
  • Configurable rate limits.
  • Non-configurable rate limits.

You can also manage service accounts through the API.

• For instance-level service accounts, use the service account users API.
• For group-level service accounts, use the group service accounts API.

View and manage service accounts

The Service Accounts page displays information about service accounts in your top-level group or instance. Each top-level group and GitLab Self-Managed instance has a separate Service Accounts page. From these pages, you can:

• View all service accounts for your group or instance.
• Delete a service account.
• Edit a service account’s name or username.
• Manage personal access tokens for a service account.

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.

Prerequisites:

• For instance-level service accounts, you must be an administrator for the instance.
• For group-level service accounts:
  • You must have the Owner role in a top-level group.
  • For GitLab Self-Managed or GitLab Dedicated, you must be allowed to create service accounts.

1. Go to the Service Accounts page.
2. Select Add service account.
3. Enter a name for the service account. A username is automatically generated based on the name. You can modify the username if needed.
4. Select Create service account.

Manage a service account

You can view, delete or edit an existing service account.

1. Go to the Service Accounts page.
2. Delete a service account by selecting the three-dot menu (⋮) and choosing Delete.
3. Edit a service account’s name or username by selecting the three-dot menu (⋮) and choosing Edit.

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:

• API.
• Group members UI.
• Project members UI.

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.

View and manage personal access tokens for a service account

The personal access tokens page displays information about the personal access tokens associated with a service account in your top-level group or instance. From these pages, you can:

• Filter, sort, and view details about personal access tokens.
• Rotate personal access tokens.
• Revoke personal access tokens.

You can also manage personal access tokens for service accounts through the API.

• For instance-level service accounts, use the personal access tokens API.
• For group-level service accounts, use the group service accounts API.

To view the personal access tokens page for a service account:

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Manage Access Tokens.

Create a personal access token for a service account

To use a service account, you must create a personal access token to authenticate requests.

Prerequisites:

• For instance-level service accounts, you must be an administrator for the instance.
• For group-level service accounts, you must have the Owner role in a top-level group.

To create a personal access token:

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Manage Access Tokens.
4. Select Add new token.
5. In Token name, enter a name for the token.
6. Optional. In Token description, enter a description for the token.
7. In Expiration date, enter an expiration date for the token.
   • The token expires on that date at midnight UTC. A token with the expiration date of 2024-01-01 expires at 00:00:00 UTC on 2024-01-01.
   • If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date.
   • By default, this date can be a maximum of 365 days later than the current date. In GitLab 17.6 or later, you can extend this limit to 400 days.
8. Select the desired scopes.
9. Select Create personal access token.

Rotate a personal access token

Prerequisites:

• For instance-level service accounts, you must be an administrator for the instance.
• For group-level service accounts, you must have the Owner role in a top-level group.

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Manage Access Tokens.
4. Select Rotate.
5. On the confirmation dialog, select Rotate.

Revoke a personal access token

Prerequisites:

• For instance-level service accounts, you must be an administrator for the instance.
• For group-level service accounts, you must have the Owner role in a top-level group.

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Manage Access Tokens.
4. Select Revoke.
5. On the confirmation dialog, select Revoke.

Delete a service account via API

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.

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

   Shell Copy to clipboard

   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.

Related topics

• Billable users
• Associated records
• Project access tokens - bot users
• Group access tokens - bot users
• Internal users

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.