Service accounts

{{< details >}}

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

{{< /details >}}

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.

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.
  • Can be owned by the entire instance or a specific top-level group.
    • On GitLab.com, service accounts must be owned by a top-level group.

You can also manage service accounts through the API.

Prerequisites

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

View and manage service accounts

{{< history >}}

  • Introduced for GitLab.com in GitLab 17.11

{{< /history >}}

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.

{{< tabs >}}

{{< tab title=”Instance-wide service accounts” >}}

To view service accounts for the entire instance:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Service Accounts.

{{< /tab >}}

{{< tab title=”Group service accounts” >}}

To view service accounts for a top-level group:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > Service Accounts.

{{< /tab >}}

{{< /tabs >}}

Create a service account

{{< history >}}

  • Introduced for GitLab.com in GitLab 16.3
  • Top-level group owners can create Service accounts 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.
  • Top-level group owners can create Service accounts generally available in GitLab 17.6. Feature flag allow_top_level_group_owners_to_create_service_accounts removed.

{{< /history >}}

On GitLab.com, you can create service accounts owned by a top-level group.

By default, on GitLab Self-Managed and GitLab Dedicated, only administrators can create service accounts. You can allow top-level group Owners to create 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, you can create one service account for every paid seat.
  • On GitLab 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.

To edit a service account:

  1. Go to the Service Accounts page.
  2. Identify a service account.
  3. Select the vertical ellipsis ({{< icon name=”ellipsis_v” >}}) > 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. On GitLab.com, service accounts for groups can only belong to a single 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 ({{< icon name=”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 ({{< icon name=”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 ({{< icon name=”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 ({{< icon name=”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.

{{< alert type=”warning” >}}

This cannot be undone. Any services that rely on the rotated token will stop working.

{{< /alert >}}

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 ({{< icon name=”ellipsis_v” >}}) > 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.

{{< alert type=”warning” >}}

This cannot be undone. Any services that rely on the revoked token will stop working.

{{< /alert >}}

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 ({{< icon name=”ellipsis_v” >}}) > Manage Access Tokens.
  4. Select Revoke.
  5. On the confirmation dialog, select Revoke.

Rate limits

Rate limits apply to service accounts: