Service accounts

{{< details >}}

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

{{< /details >}}

{{< history >}}

• Service accounts on Free tier:
  • Introduced in GitLab 18.10 with a flag named service_accounts_available_on_free_or_unlicensed. Disabled by default.
  • Generally available in GitLab 18.11. Feature flag removed.
• Project service accounts introduced in GitLab 18.10 with a flag named allow_projects_to_create_service_accounts. Disabled by default.
• Subgroup service accounts introduced in GitLab 18.10 with a flag named allow_subgroups_to_create_service_accounts. Disabled by default.
• Subgroup and project service accounts generally available in GitLab 18.11. Feature flags allow_subgroups_to_create_service_accounts and allow_projects_to_create_service_accounts removed.

{{< /history >}}

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 have the following characteristics:

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

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

The number of service accounts you can create depends on your subscription and offering:

• On GitLab Premium and Ultimate, you can create an unlimited number of service accounts for all offerings.
• On GitLab Free, limits vary by offering:
  • For GitLab.com, you can create up to 100 service accounts for each top-level group. This includes service accounts created in subgroups or projects.
  • For GitLab Self-Managed Enterprise Edition (EE), you can create up to 100 service accounts instance-wide.
  • For GitLab Self-Managed Community Edition (CE), you cannot create service accounts.

Types of service accounts

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

{{< tabs >}}

{{< tab title="Instance service accounts" >}}

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.

{{< /tab >}}

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

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:
  • Be an administrator for the instance.
  • Have the Owner role in a group and be allowed to create service accounts.

{{< /tab >}}

{{< tab title="Project service accounts" >}}

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.

{{< /tab >}}

{{< /tabs >}}

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 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.

{{< tabs >}}

{{< tab title="Instance service accounts" >}}

To view service accounts for the entire instance:

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

{{< /tab >}}

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

To view service accounts for a group:

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

{{< /tab >}}

{{< tab title="Project service accounts" >}}

To view service accounts for a project:

1. In the top bar, select Search or go to and find your project.
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, 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 depends on your subscription and offering:

• On GitLab Premium and Ultimate, you can create an unlimited number of service accounts for all offerings.
• On GitLab Free, limits vary by offering:
  • For GitLab.com, you can create up to 100 service accounts for each top-level group. This includes service accounts created in subgroups or projects.
  • For GitLab Self-Managed Enterprise Edition (EE), you can create up to 100 service accounts instance-wide.
  • For GitLab Self-Managed Community Edition (CE), you cannot 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

{{< history >}}

• Added username limits for service accounts with composite identities in GitLab 18.9.

{{< /history >}}

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

[!note] 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 ({{< icon name="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:

• The GitLab UI:
  • Add users to a group.
  • Add users to a project.
• The API:
  • The group members API.
  • The project members API.

[!note] 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:

   shellCopy

    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 ({{< 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.

• For instance service accounts, use the users API.
• For group service accounts, use the 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 service accounts, use the personal access tokens API.
• For group service accounts, use the 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 ({{< 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.

[!warning] 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 ({{< icon name="ellipsis_v" >}}) > Manage access tokens.
4. Next to an active token, select the vertical ellipsis ({{< icon name="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.

[!warning] 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 ({{< icon name="ellipsis_v" >}}) > Manage access tokens.
4. Next to an active token, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
5. Select Revoke.
6. 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