Service accounts

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

Service accounts are user accounts that represent non-human entities rather than individual people. 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 stay stable regardless of changes to your team’s membership.

Service accounts authenticate with a personal access token. They can interact with package and container registries, perform Git operations, and access the API.

Service accounts:

  • Do not use a seat.
  • Cannot sign in to GitLab through the UI.
  • Cannot be managed through services such as LDAP.
  • Appear in group and project membership lists as service accounts.
  • Do not receive notification emails unless you add a custom email address.
  • Are not billable users or internal users.
  • Are available on trial versions of GitLab. On GitLab.com, the Owner of the top-level group must verify their identity first.
  • Cannot create top-level groups or other service accounts. when provisioned by a subgroup or project.

You can also manage service accounts through the service accounts API.

Types of service accounts

Service accounts have three types, each with a different scope and prerequisites:

Instance service accounts are created through the Admin area, and can be invited to any group or project on the instance.

Prerequisites:

  • Administrator access to the instance.

Group service accounts are created by a specific group and can be invited to the group where they were created or to any descendant subgroups or projects. They cannot create top-level groups or service accounts.

Prerequisites:

  • On GitLab.com, you must have the Owner role for the group.
  • On GitLab Self-Managed or GitLab Dedicated, you must either:

Project service accounts are created by a specific project and are available only to that project. They cannot create top-level groups or service accounts.

Prerequisites:

  • On GitLab.com, you must have the Owner or Maintainer role for the project.
  • On GitLab Self-Managed or GitLab Dedicated, you must either:
    • Be an administrator for the instance.
    • Have the Owner or Maintainer role in a project.

View and manage service accounts

The service accounts page displays information about service accounts in your group, project, or instance. Each group, project, 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.

To view service accounts for the entire instance:

  1. In the upper-right corner, select Admin.
  2. Select Settings > Service accounts.

To view service accounts for a group:

  1. On the top bar, select Search or go to and find your group.
  2. Select Settings > Service accounts.

To view service accounts for a project:

  1. On the top bar, select Search or go to and find your project.
  2. Select Settings > Service accounts.

Create a service account

On GitLab.com, only top-level group Owners can create service accounts.

By default, on GitLab Self-Managed and GitLab Dedicated, only administrators can create either type of service account. However, you can configure the instance to allow top-level group Owners to create group service accounts.

The number of service accounts you can create is limited by your license:

  • On GitLab Free, you cannot create service accounts.
  • On GitLab Premium and Ultimate, you can create an unlimited number of 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.

You cannot update the username of a service account associated with a composite identity.

To edit a service account:

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

Add a service account to a group or project

Service accounts have limited access until you add them as members of a group or project. You can add any number of service accounts to a group or project, and each service account can have a different role in each group, subgroup, or project.

Service account access depends on the type of service account:

  • Instance service accounts: Can be invited to any group or project on the instance.
  • Group service accounts: Can be invited to the group where they were created or to any descendant subgroups or projects.
  • Project service accounts: Can be invited only to the project where they were created.

When a group is shared with another group, all members of that group, including service accounts, gain access to the shared group.

You can assign service accounts to groups and projects using:

If the global SAML group memberships lock or the global LDAP group memberships lock settings are enabled, you must use the API to control service account memberships.

Fork projects with a service account

Service accounts can fork projects through the Project forks API, but cannot fork to their personal namespace. When forking with a service account, you must specify a target group namespace.

Prerequisites:

  • The service account has the Developer role and is a member of the target group.
  • The api scope is turned on for the service account’s personal access token.

To fork a project using a service account:

  1. Identify the target group where the fork is created.

  2. Ensure the service account is a member of that group with appropriate permissions.

  3. Use the fork project API with either namespace_id or namespace_path:

     curl --request POST --header "PRIVATE-TOKEN: <service_account_token>" \
   --data "namespace_path=target-group" \
   "https://gitlab.example.com/api/v4/projects/<project_id>/fork"

Delete a service account

When you delete a service account, any contributions made by the account are retained and ownership is transferred to a ghost user. 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 ( ellipsis_v ) > 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 ( ellipsis_v ) > 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.

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.

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 ( ellipsis_v ) > 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 ( ellipsis_v ) > 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.

This cannot be undone. Services that rely on the rotated token stop working.

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 ( ellipsis_v ) > Manage access tokens.
  4. Next to an active token, select the vertical ellipsis ( ellipsis_v ).
  5. Select Rotate.
  6. On the confirmation dialog, select Rotate.

Revoke a personal access token

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

This cannot be undone. Services that rely on the revoked token stop working.

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 ( ellipsis_v ) > Manage access tokens.
  4. Next to an active token, select the vertical ellipsis ( ellipsis_v ).
  5. Select Revoke.
  6. On the confirmation dialog, select Revoke.

Rate limits

Rate limits apply to service accounts: