Git tokens for GitOps
Understand Git tokens and scopes required for GitOps
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 which Codefresh uses 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
At all times, both tokens are always securely stored on your cluster and never stored 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 |
|
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 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 |
|
GitLab Cloud and GitLab Server | Can be personal or group-based:
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 |
|
Git Runtime token in values.yaml
You also have the option to directly add your Git Runtime token, or a reference to a secret that contains the Git Runtime token, to values.yaml
(typically the latter).
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 |
|
GitLab Cloud and GitLab Server |
|
Bitbucket Cloud and Bitbucket Server |
|
Git user tokens with custom scopes
Codefresh validates Git user tokens and their associated scopes when authorizing Git actions for the Runtime.
If you require custom scopes in Git user tokens that don’t meet the default Codefresh requirements, you can create Git user tokens with custom scopes. You may want to have Git user tokens without admin
scopes, or use the new fine-grained tokens for GitHub (currently not officially supported by Codefresh).
Codefresh provides the skipGitPermissionValidation
flag which you can add to your values.yaml
file to bypass token validation for such cases.
app-proxy:
config:
skipGitPermissionValidation: "true"
If you set this flag, make sure that:
- 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 multiplerepo-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.
Use same Git user tokens for multiple GitOps Runtimes
If a user has access to multiple GitOps Runtimes in the same or in different accounts in Codefresh, they can use either the same Git user token to authenticate and authorize all the Runtimes to which they have access.
NOTE
The user must configure the Git user token for each GitOps Runtime separately.
Manage Git user tokens
User can manage their Git user tokens for Runtimes, as described in Managing Git PATS.
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.
Related articles
Managing Git PATs
User settings
Secrets for GitOps
Verifying authenticity of Codefresh artifacts