Service accounts

Overview

A service account is an identity nobody logs into — a deploy bot, a release script, a nightly job — that belongs to a group or a single repository instead of to a person. It carries its own access level, authenticates with tokens minted for it, and appears in history under its own name, so your automation keeps working when the engineer who set it up changes team.

Give one the smallest access level that does its job, point your automation at its token, and revoke that token when the automation retires. Deleting the account takes every token issued for it with it, which is what makes a service account a safer home for a long-lived credential than somebody's personal token.

Quick start

Before you start

How it works

Where an account lives, and how far it reaches

Every service account is owned by exactly one scope, and its access level applies to that scope and everything nested inside it.

A group account with Developer level can push to every repository in that group's subtree, including ones created after the account was. A repository account reaches that one repository and nothing else. There is no way to add a service account to a second scope: if a bot needs to work in two unrelated places, either create one account in each, or create a single account on the nearest group that contains both.

That reach is also why a service account does not appear in a scope's member list. Its access level is part of the account itself rather than a membership you could remove separately, so it lives and dies with the account and shows up under Service accounts rather than under Members.

The name you choose and the identity we generate

You choose one thing: the display name, between 1 and 100 characters, and it is the only part meant for humans. The username and the email address are generated for you at creation and never change — not when you rename the account, not when the group is renamed. A group account's username reads sa_group_9f2c1a04_7b3d81: the kind of scope, the first eight characters of that scope's id, and six random ones. A repository account's reads sa_repository_… instead. The email is that username at @noreply.gitmoap. Nothing is delivered to that address; it exists so the account can be an author, an assignee and a commit identity like anyone else.

Nothing about creation is idempotent. Two calls with the same name produce two separate accounts with two separate identities, so a provisioning script that runs twice leaves you with a duplicate bot rather than the one you meant.

You cannot create an account more powerful than you are

The level you assign is compared against your own level on the scope, and anything higher is refused. The same ceiling applies when you raise an existing account's level later, so there is no two-step route around it.

No account is an Owner, whoever creates it: Maintainer is the highest level a service account can hold. Owner is the level that changes who else has access, and that stays with people.

Who can see one, and what is recorded

Names, levels and creation details are readable by anyone who can read the scope — on a public or internal group or repository, that is every signed-in person. Tokens are never part of that: no listing, detail view or export contains a secret, and a token's plaintext is shown exactly once, at the moment it is minted.

Reading a single service account is recorded in the audit log, as is every create, rename, level change, picture change and delete. Listing is not. If you need to prove who gave a bot Maintainer and when, that is the record to read.

How to

Create a service account for a whole group

Pick the group whose subtree the account should work in, give it a name a human will recognise in an activity list, and give it a level. Start lower than feels comfortable — Reporter reads, Developer pushes to unprotected branches and opens merge requests, Maintainer pushes to protected branches and changes settings. Raising the level later is one call; discovering a bot had Owner for a year is not recoverable.

Creating the account does not give it any credentials. It cannot do anything at all until you mint it a token.

Create a service account for one repository

Use this when the automation only ever touches one repository — a deploy job, a docs publisher, a bot that labels merge requests. The account has no standing anywhere else in the tree, so a leaked token cannot be pointed at a sibling repository.

Find the service accounts in a group or repository

Accounts come back newest first, with their level, their generated username and who created them. A group's listing shows the accounts owned by that group; it does not include the accounts owned by its child groups and repositories, which are listed on those.

Look up one service account

Useful when a comment, a work item or a commit turns out to be the work of sa_repository_… and you want to know what it is, who created it and what it can do.

Give a service account its credentials

A service account authenticates with tokens minted for it, which begin gms_. Minting one needs token:manage on your own token as well as the standing to manage the account — Owner on the group for a group account, Maintainer on the repository for a repository one, and a level at least the account's own — and the plaintext is shown once and never again.

Replace <service-account-id> with the id from gitmoap sa list-group --group-id <your-group> --output json. A token cannot raise the account's access level: one carrying git:write still pushes as a Reporter if that is what the account is. If you bind the token to a group or repository, that scope has to be one you can see yourself. And minting, like creating, has to be done as a person — a service account's own token cannot mint tokens, for itself or for anything else. The full treatment, including expiry, resource binding and revocation, is in Access tokens.

Change a service account's name or access level

Renaming is cosmetic and safe. Changing the level takes effect on the account's very next request, including requests already in flight from a running job, and applies to every token the account holds — you cannot give one token more reach than another by editing the account.

At least one field has to change; an empty update is refused rather than treated as a no-op.

The scope is not editable here, and there is no route that makes it editable. Moving a bot from one group to another means creating a new account in the destination, minting it a token, switching your automation over, then deleting the old one.

Give a service account a picture

A picture makes a bot's activity obvious at a glance in a busy discussion. Uploading happens in two steps: ask for an upload address, then send the image bytes to it yourself.

You have to declare the exact byte size up front. That number is bound into the upload address, so an upload that sends a different number of bytes is rejected by the storage service rather than silently truncated, and the address itself stops working after five minutes. image/png, image/jpeg, image/gif and image/webp are accepted; anything else is refused before an address is issued.

An account can instead carry the address of a picture you host elsewhere, set with the avatar field when you create or update it. When that is set it wins over anything uploaded here.

Remove a service account's picture

Removing the picture deletes the stored image, and no copy is kept — keep the original file somewhere if you might want it back. The account keeps working exactly as before and falls back to the default image derived from its generated address.

Retire a service account

Before you delete, find out what is still using it. The account's own contribution history shows what it has been doing and how recently, and its token list shows how many credentials exist and when each was last used. A bot with a token used in the last hour is a bot something depends on.

An account that has left records behind often cannot be deleted at all. While it is still named as the creator of something the platform keeps — a comment it wrote, a work item it filed, a release it cut, a pipeline run it started — the delete is refused with 409 CONFLICT rather than performed, so the record is never quietly detached from whoever made it. Revoking its tokens is the way to retire a bot that has done work.

If you only need to stop it temporarily, revoke its tokens instead and keep the account. Revoking is reversible in the sense that matters — you mint a new token when you want the bot back — and it leaves the identity, its history and its level intact.

Deleting the owning group or repository deletes its service accounts too, with the same consequences and no separate confirmation.

Reference

Limits

Service accounts per scope — 10 on the Free plan. The cap is counted per scope, not per tree: a group can hold 10 of its own while each repository inside it holds its own 10, and accounts belonging to a child scope never count against the parent's allowance.

At the cap, a create call is refused with 429 TOO_MANY_REQUESTS and nothing is created — no half-made account, no orphaned identity, nothing to clean up. Delete an account you no longer need, move the automation to a group account that serves several repositories, or raise the ceiling: a higher plan lifts every scope's allowance, and an Owner can ask for a higher limit on one namespace. To know how close a scope is before a script finds out for you, count the accounts in its own listing.

Pictures — 5 MiB per upload. You declare the exact size when you ask for an upload address; 0 bytes or anything over 5 MiB is refused with 400 BAD_REQUEST before an address is issued, and the address that comes back accepts exactly that many bytes and expires after five minutes.

One more ceiling worth knowing, because it is the one a busy bot meets: a single account holds at most 100 tokens. Revoke the ones you have stopped using rather than accumulating them — Access tokens covers listing and revoking.

Troubleshooting

Examples

Provision a deploy bot for a group, end to end

Creates a Developer-level account for everything under acme/platform, mints it a 90-day token that can push, and prints the token once.

Put that last value straight into your CI secret store — it is not retrievable afterwards. Your job then authenticates git with it:

Audit what a scope's bots can do

Lists a group's accounts newest first with just the fields worth reviewing, which makes an over-privileged account easy to spot.

Anything at maintainer deserves a reason. Lower one with gitmoap sa update --sa-id <id> --access-level developer, which takes effect on that account's next request.

FAQ

Related