Create Service Accounts for Programmatic and CI/CD Access
For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append.mdto anykestra.io/docs/*URL for plain Markdown.
Available on: Enterprise EditionCloud
Service accounts represent applications or CI/CD systems that access Kestra programmatically, without a password or UI access. Each service account has a name, an optional description, an optional group assignment, and a list of roles that grant it permissions to specific resources.
Service accounts vs. users
Service accounts have no password and no access to the Kestra UI — they authenticate exclusively via API token. Users, by contrast, can interact with both the UI and the API using a password or an API token.
Creating a service account
Service accounts are created under IAM → Service Accounts. Each has a name, optional description, optional group assignment, and roles that grant access to specific resources. API tokens are generated from the service account’s details view and are shown only at creation.
Users, service accounts, and API tokens
You can create an API token for a regular user as well. While service accounts are recommended for programmatic access from CI/CD or external applications, user API tokens are useful when you want programmatic actions to be tracked and audited against a specific person.
The key difference: a service account has no password or personal information and is authenticated exclusively with an API token. A user can interact with both the UI and the API, using either a password or an API token.
Allocating service accounts to groups
Each service account can be attached to one or more groups, such as a “Bots” group that centrally governs programmatic access for CI/CD across multiple projects with a single role.
CLI token usage
kestractl authenticates with a service account’s API token through the --token flag or the KESTRACTL_TOKEN environment variable. This uploads the contents of the local scripts folder to the scripts folder of the prod namespace’s files:
export KESTRACTL_HOST=https://kestra.example.comexport KESTRACTL_TOKEN=<service-account-api-token>kestractl nsfiles upload prod ./scripts scripts --no-root --overrideIn CI pipelines, store the token as a masked secret instead of writing it in the pipeline file.
Service account name convention
Follow the DNS naming convention when naming service accounts. The name property must:
- contain at most 63 characters
- contain only lowercase alphanumeric characters or hyphens (
-) - start with an alphanumeric character
- end with an alphanumeric character.
Examples:
- ✅
my-service-accountis a valid name - ✅
my-service-account-1is a valid name - ❌
MY_SERVICE_ACCOUNTis not a valid name because it contains uppercase characters and underscores - ❌
myServiceAccountis not a valid name because it contains uppercase characters and camel case - ❌
my-service-account-is not a valid name because it ends with a hyphen.
Kestra uses the DNS-style naming convention so that service account names remain valid across contexts where they may be forwarded, such as Kubernetes pod labels.
Was this page helpful?