Service Accounts

Give CI pipelines and automation an identity of their own, with its own roles and keys.

A service account is an identity for a CI pipeline, a scheduled job or an integration. It has its own roles and its own keys. It continues to work when the person who created it leaves the organization.

Use a service account instead of a personal API key for every pipeline. A personal key has all the access of its owner, and it stops when the owner leaves.

Organization and project service accounts

Organization service accountProject service account
Who creates itAn organization admin or owner. Only an owner gives it the admin role.A project admin
Roles it can holdOrganization member or admin, and a role in any project of the organizationA role in its own project only
Where you manage itService Accounts of the organizationService Accounts of the project
When its project is deletedIt staysIt is deleted with the project

A service account is never an organization owner. An organization service account gets the default project role, like a member. A project service account gets a role in its project only when you grant one.

A service account has a name, for example ci-deploy, and a display name. The name is unique in its organization or project, and it never changes. The API and the CLI use the name. Member lists show the display name with a bot icon. To change the display name, the description or, for an organization service account, the organization role, select Edit in the row menu of the console.

Set up a service account for a pipeline

  1. In the console, open your organization or project, then Service Accounts.
  2. Select Create service account, and give it a name, for example ci-deploy. A display name is optional.
  3. In the row menu, select Project role. Select the project and a role. Writer can create and run sandboxes.
  4. In the row menu, select API Keys, then Create API key. Select an expiry.
  5. Copy the key. Tektona shows it once.
  6. Store the key as a secret of your pipeline. The Tektona CLI and SDKs read it from TEKTONA_API_KEY.

These steps need a console sign-in: create, change or enable a service account, grant a role, and create or roll a key. An API key cannot do these steps, so a stolen key cannot mint a new credential. The CLI lists, disables and deletes service accounts and keys:

tektona service-account ls
tektona service-account key ls ci-deploy
tektona service-account ls --scope project

--scope project works on the service accounts of the context project.

Share the sandboxes of a pipeline

A sandbox is private when it is created. Only its owner and the project admins see it, so a project member cannot debug a sandbox that a pipeline created. To share it, create it with --share use. Project members can then operate it. With --share manage, they can also delete it.

tektona sandbox create go-dev --share use

A shared sandbox runs with the credentials of its owner. Every member who can operate it reaches those credentials.

The console shows a Service account badge on the owner of a sandbox that a service account owns. In the API, the owner of the sandbox has the kind service_account.

Keys

  • Every key expires. The expiry is at most 1 year after you create the key.
  • A service account has at most 2 active keys at a time.
  • The key list shows when Tektona last saw each key, accurate to 5 minutes.
  • A service account key starts with tektona_sa_ and ends with a checksum. Secret scanners can find a leaked key by this pattern.
  • You create or roll a key only when you hold every project role of the service account yourself, the default project role included. An organization owner holds every role.
  • A project role grant fails while the service account has an active key whose creator does not hold that role in the project. The same applies when you remove an organization service account from a project and it falls back to a higher default project role.
  • A change of the organization default project role does not check keys. When you raise the default, roll the keys of organization service accounts whose creators have a lower role in a project.
  • A grant of the organization admin role fails while the service account has an active key whose creator is not an organization admin or owner.
  • A key continues to work when the person who created it leaves. The API names the creator of each key (created_by_user_id). Roll the keys of a person who leaves.

Fix a grant that a key creator blocks

Do one of these steps:

  • Delete the key.
  • Have someone who holds the role roll the key with no grace period. Then wait 5 minutes. For the organization admin role, this is an admin or owner.

A roll needs a free key slot. With 2 active keys, delete one key first.

Rotate a key without an outage

Roll the key in the console: open Keys, then select Roll in the key menu. A roll creates a new key. The old key continues to work for a grace period. Deploy the new key during the grace period.

The grace period is from 0 to 7 days, and 24 hours by default. The old key never works longer than its own expiry. A roll fails when the service account already has 2 active keys. Delete the older key first.

What a service account key cannot do

A service account key cannot read or manage service accounts, keys or memberships, and it cannot create an organization or a project. A stolen key thus cannot create more keys or grant itself more access.

Disable or delete a service account

Only an organization owner disables, deletes or changes a service account with the admin role.

  • Disable stops every key of the service account within seconds. Its sandboxes continue to run.
  • Enable in the console makes the keys that did not expire work again. Enable fails while a key's creator no longer holds one of the account's roles, because a disable can be the way to cut that person off. To fix it, follow Fix a grant that a key creator blocks.
  • Delete removes the service account, its keys and its roles. Its sandboxes stay. An admin transfers or deletes them.

On this page