Skip to main content
Requires Enterprise plan. Contact sales for access.
Service accounts are non-human identities that run automations independently of individual users. They decouple credentials from personal accounts, ensuring workflows continue when team members leave. Automated actions are attributed to the service account, making it easy to distinguish agent activity from human work. Manage service accounts in Settings → Members → Service Accounts. Only admins can create or delete them.
Service Accounts page showing list of accounts with names and expiration dates

​
Create a service account

  1. Go to Settings → Members → Service Accounts
  2. Click Create New Service Account
  3. Enter a name and optional description
  4. Click Create
Service accounts expire 1 year from creation.
Service account creation form with name and description fields

​
Git authentication

Service accounts need Git authentication to clone repositories, commit changes, and create pull requests. Only PAT-based authentication is supported.

​
Add Git authentication

  1. Open the service account details page
  2. Click Add Git Authentication
  3. Select the environment class where the automation will execute
  4. Choose your Provider (GitHub or GitLab)
  5. Enter a Personal Access Token from your SCM
Git authentication setup showing environment class, provider selection, and PAT input fields

​
Create a personal access token

GitHub:
  1. Go to Settings > Developer settings > Personal access tokens > Tokens (classic)
  2. Click Generate new token
  3. Select scopes: repo, read:user, user:email, workflow
  4. Copy the token
GitHub documentation: Creating a personal access token GitLab:
  1. Go to Preferences > Access Tokens
  2. Enter a name and expiration date
  3. Select scopes: api, read_repository, write_repository
  4. Click Create personal access token
  5. Copy the token
GitLab documentation: Personal access tokens
Store the token securely. You won’t be able to see it again after creation.

​
Commit attribution

When a service account commits changes, the Git author email is determined by the account that owns the Personal Access Token. This affects how commits appear in your repository history and audit logs.
  • GitHub: The PAT owner’s primary email address is used for commit attribution
  • GitLab: The PAT owner’s email address is used, but email verification policies may apply (see below)
Organizations with audit or compliance requirements should ensure the PAT is created from an account with an appropriate email address.

​
Platform-specific considerations

​
GitLab email verification limitation

GitLab service accounts cannot have verified email addresses. If your organization requires verified emails for Git commits, you must use a dedicated real GitLab user account instead of a GitLab service account.
Many organizations enforce policies requiring all Git commits to use verified company domain emails (e.g., @company.com) for security and audit compliance. GitLab’s native service accounts have a limitation that prevents this:
  • GitLab service accounts can have custom email addresses assigned via API
  • However, these emails remain in an unconfirmed state and cannot be verified
  • Service accounts cannot sign in to the GitLab UI to complete email verification
  • Even with a verified domain configured in GitLab, service account emails are not automatically confirmed
This is a known GitLab limitation. Workaround for GitLab users with email verification policies:
  1. Create a dedicated real GitLab user account (e.g., [email protected])
  2. Verify the email address by signing in and completing verification
  3. Generate a Personal Access Token from this dedicated user account
  4. Use this PAT when configuring Git authentication for your Ona service account
This approach gives you the benefits of Ona service accounts (decoupled credentials, clear attribution) while satisfying GitLab’s email verification requirements.

​
GitHub

GitHub does not have the same email verification restrictions for automated commits. Personal Access Tokens work with any GitHub account type, including machine users and bot accounts.

​
Tokens

Service Account Tokens (SATs) are long-lived credentials for authenticating with the Ona API. Use them for CI/CD pipelines, external scripts, or any programmatic access that needs to act as the service account. Tokens are valid for up to 90 days. Only organization admins can create tokens on behalf of a service account.
SATs can be used to start automations and perform read operations (GET/LIST) on the API. For additional use cases, contact the Ona team.

​
Create a token

  1. Open the service account details page
  2. Go to the Tokens section
  3. Click New Token
  4. Enter a description and select a validity period (30, 60, or 90 days)
  5. Click Create
  6. Copy the token immediately—it won’t be shown again
Service account token creation dialog
Token copy dialog showing the token value
Store tokens in a secure secret manager (GitHub Secrets, HashiCorp Vault, AWS Secrets Manager). Never commit tokens to repositories.

​
Use a token

Include the token in API requests as a Bearer token: 
curl -H "Authorization: Bearer $GITPOD_SA_TOKEN" \
  https://api.gitpod.io/gitpod.v1.EnvironmentService/ListEnvironments

​
Revoke a token

To revoke a token:
  1. Open the service account details page
  2. Go to the Tokens section
  3. Click the delete icon next to the token
  4. Confirm deletion
Suspending or deleting the service account also revokes all its tokens immediately.

​
Secrets

Service accounts can have secrets attached. Secrets are injected into environments based on identity—when an environment runs as a service account, that service account’s secrets are available. This works the same way as user secrets. Organization and project secrets are also available, following the standard precedence rules.

​
Create a secret

  1. Open the service account details page
  2. Go to the Secrets section
  3. Click New Secret
  4. Select the secret type:
    • Environment Variable — injected as an environment variable
    • File — mounted at a specified path
    • Container Registry — credentials for private registries
  5. Enter the secret details and click Create
Service account secret creation dialog
For details on each secret type, see Secrets.

​
Using service accounts in automations

When creating or editing an automation, select a service account from the Run as dropdown. The automation will use the service account’s identity and Git credentials for all repository operations. For detailed guidance, see Service Accounts for Automations.

​
Delete a service account

  1. Navigate to Settings → Members → Service Accounts
  2. Click on the service account name
  3. Click Delete Service Account
  4. Confirm deletion
A service account cannot be deleted if it is currently used by any automation. Update affected automations to use a different executor first.

​
Next steps