Improve this page on GitHub

Git tokens for GitOps

Understand Git tokens and scopes required for Git authentication

Codefresh requires two types of Git tokens for authentication in GitOps, a Git Runtime token, and a Git user token. The Runtime and user tokens are both Git access tokens used for different purposes. See Git Runtime tokens versus Git user tokens in Codefresh.

The Git Runtime token is mandatory for every GitOps Runtime. It must be provided during the Runtime installation, and is typically associated with a service/robot account.
The Git user token is an access token that is unique to every user in the Codefresh platform. It is required after installation for every Runtime which the user has access to.

IMPORTANT
Both tokens are always securely stored on your cluster and never locally on our platform.

Users can also create and use Git tokens with custom scopes for both GitOps Runtimes and for Git repositories associated with the Runtimes that they need to access. See Git user tokens with custom scopes.

Git Runtime tokens versus Git user tokens in Codefresh

The table below summarizes the main differences between the Git Runtime token and Git user tokens in Codefresh.

	Git Runtime token	Git user token
Usage	During installation, to create the Shared Configuration Repository to store shared runtime settings and install the GitOps Runtime. After installation, used by: Argo CD to clone the Git repos, pull changes, and sync to the K8s cluster. Used during promotion to perform commits, and pull requests for GitHub. Argo Events to create web hooks in Git repositories. `cap-app-proxy` to clone the Shared Configuration Repository	Authenticate and authorize user actions in Codefresh UI and CLI to Git repositories for every provisioned GitOps Runtime. Users can view and manage the Git user tokens assigned to the Runtimes in the Git Personal Access Token page.
Created	Before Runtime installation; see required scopes for Git Runtime tokens.	After Runtime installation; see required scopes for Git user tokens.
Managed by	Admin at account-level	User
Associated Account Type	(Recommended) Service account or robot account	User account

Git token conversion to secret

Codefresh needs access to Git repositories for reading and writing to configuration and resource manifests. This section elaborates on how Git providers and repositories with Git tokens for authentication to .

GitOps Runtime token and secret

The Git Runtime token is the personal access token provided during Runtime installation and is automatically converted to a secret. The secret for the Runtime repository is stored in the runtime-repo-creds-secret secret, labeled with argocd.argoproj.io/secret-type: repo-creds.

This label The Runtime uses the same credentials

The secret:

Allows Argo CD to use the credentials to clone and pull data from the repositories it syncs from for read-only operations.
Allows the Runtime to both read and write to the same repositories, for all actions on behalf of the Runtime such as commits during promotions.

GitOps user token and secret

The Git user token, also a personal access token, is used for operations initiated by the user via the UI, and is therefore unique to each user.
The Git user token is also converted to an encrypted secret, and stored in the git-default-<account-id> secret.

The token is used to:

Perform Git commits and pushes on behalf of the user.
Validate the user’s access permissions to specific Git repositories and determine application visibility.

Git Runtime token scopes

The table below lists the scopes required for Git Runtime tokens for the different Git providers. You can also create a Git Runtime token with custom scopes and add it directly to the values.yaml file.

Git provider	Required scopes for Git Runtime token
GitHub and GitHub Enterprise	Classic: `repo` `admin:repo_hook` Fine-grained (personal or group-based): Repository access: `All repositories` or `Only select repositories` including all repos that Argo CD syncs from Repository permissions: Administration: `Read and write` Commit statuses: `Read and write` Contents: `Read and write` Metadata: `Read-only` Pull requests: `Read and write` Webhooks: `Read and write`
GitLab Cloud and GitLab Server	Can be personal or group-based: `api` (includes `read_api`, `read_repository`, and `write_repository`) NOTE For personal tokens, the token must have `write` access to the Shared Configuration Repository, and `read` access to all the repositories that Argo CD syncs from. For group tokens, the group must include all the repositories that Argo CD syncs from.
Bitbucket Cloud and Bitbucket Server	Account: `Read` Workspace membership: `Read` Webhooks: `Read and write` Repositories: `Write, Admin`

Git Runtime token in values.yaml

You can directly add the Git Runtime token, or a reference to the Runtime secret, to your values.yaml.

To skip token validation both during installation and upgrade in this scenario, add the skipValidation flag to values.yaml.

installer:
  skipValidation: true

IMPORTANT
If you set the flag to skip validation, the onus is on you to provide a valid and secure token.

Git user access token scopes

The table below lists the scopes required for Git user access tokens for the different Git providers. As with the Git Runtime token, you can create and use Git user tokens with custom scopes per GitOps Runtime and per Git repository to which the Runtime has access.

Git provider	Required scopes for Git user token
GitHub and GitHub Enterprise	Classic: `repo` Fine-grained: Repository access: `All repositories` or `Only select repositories` Repository permissions: Contents: `Read and write` Metadata: `Read-only`
GitLab Cloud and GitLab Server	`write_repository` (includes `read_repository`) `api_read`
Bitbucket Cloud and Bitbucket Server	Account: `Read` Workspace membership: `Read` Webhooks: `Read and write` Repositories: `Write, Admin`

Skipping token validation in values.yaml

If you use tokens with custom scopes, or GitHub’s fine-grained tokens (currently not officially supported by Codefresh), you must skip token validation in the values.yaml file to avoid validation failures when installing GitOps Runtimes.
Codefresh validates the values.yaml before initiating Runtime installation.

Add the skipGitPermissionValidation flag to your values.yaml file to bypass token validation:

app-proxy:
  config:
    skipGitPermissionValidation: "true"

If you set this flag, make sure that:

You configure the Git user token for each GitOps Runtime separately.
The Git user token defined for the GitOps Runtime (the token defined for runtime-repo-creds-secret), has read and write access to the Shared Configuration Repository.
The Git user tokens for the different Git repositories associated with the Runtimes have read and write permissions to those Git repositories they expect to write to and read from.
Read more on configuring the repositories with multiple repo-creds secrets in Argo CD Repositories.

IMPORTANT
If you set the flag to skip validation, the onus is on you to provide valid and secure tokens. Codefresh does not validate the tokens whenever Git Runtime and Git user tokens are updated.

Best practices for Git token usage

Use a service/robot account for GitOps Runtimes

For GitOps Runtime installation, we recommend using an account not related to any specific user in your organization. Service/robot accounts are ideal for this purpose, as they provide secure authentication, restricted permissions, and centralized management.

You need to create a service or robot account with your Git provider, generate the Git Runtime token, and use this account exclusively to install GitOps Runtimes.

Use the same Git user tokens for multiple GitOps Runtimes

If a user has access to multiple GitOps Runtimes, either within the same or across different Codefresh accounts, they can use the same Git user token to authenticate and authorize all the Runtimes to which they have access. This approach simplifies token management and ensures consistency in authentication.

**NOTE
The user must configure the Git user token for each GitOps Runtime separately.

Manage Git user tokens

Users can manage their Git user tokens for Runtimes, as described in Managing Git PATS.

Managing Git PATs
User settings
Secrets for GitOps
Verifying authenticity of Codefresh artifacts