Service accounts

Service accounts are user accounts that represent non-human entities rather than individual people. You can use service accounts to perform automated actions, access data, or run scheduled processes. Service accounts are commonly used in pipelines or third-party integrations where credentials must remain stable and unaffected by changes in human user membership.

You authenticate as a service account with a personal access token. Service accounts have the same abilities as human users, and can perform actions like interacting with package and container registries, performing Git operations, and accessing the API.

There are two types of service accounts:

Service accounts:

• Do not use a seat.
• Cannot sign in to GitLab through the UI.
• Are identified in the group and project membership as service accounts.
• Do not receive notification emails without additional configuration.
• Are not billable users or internal users.
• Cannot be used with trial versions of GitLab.com.
• Can be used with trial versions of GitLab Self-Managed and GitLab Dedicated.

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.

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.

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 group-level service accounts on GitLab Self-Managed or GitLab Dedicated, you must be allowed to create service accounts.

To create a service account:

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.

Edit a service account

You can edit the name or username of a service account.

To edit a service account:

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Edit.
4. Edit the name or username for the service account.
5. Select Save changes.

Service account access to groups and projects

Service accounts are similar to external users. When first created, they have limited access to groups and projects. To give a service account access to resources, you must add it to each group or project.

There is no limit to the number of service accounts you can add to a group or project. Service accounts can have different roles in each group, subgroup, or project they are a member of. However, group-level service accounts can only belong to one top-level group.

You can manage service account access to groups and projects the same way you manage access for human users. For more information, see groups and members of a project.

You can also manage group and project assignments with the members API.

Delete a service account

When you delete a service account, any contributions made by the account are retained and ownership is transfered to a system-wide ghost user account. These contributions can include activity such as merge requests, issues, projects, and groups.

To delete a service account:

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Delete Account.
4. Enter the name of the service account.
5. Select Delete user.

You can also delete the service account and any contributions made by the account. These contributions can include activity such as merge requests, issues, groups, and projects.

1. Go to the Service Accounts page.
2. Identify a service account.
3. Select the vertical ellipsis ( ) > Delete Account and Contributions.
4. Enter the name of the service account.
5. Select Delete user and contributions.

You can also delete service accounts through the API.

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

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.

To create a personal access token for a service account:

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

You can rotate a personal access token to invalidate the current token and generate a new value.

To rotate a personal access token for a service account:

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

You can rotate a personal access token to invalidate the current token.

To revoke a personal access token for a service account:

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.

Rate limits

Rate limits apply to service accounts:

• On GitLab.com, GitLab.com-specific rate limits apply.
• On GitLab Self-Managed and GitLab Dedicated, these rate limits apply:
  • Configurable rate limits
  • Non-configurable rate limits

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.