Improve this page on GitHub

Git tokens

Codefresh requires two types of Git tokens for authentication in GitOps, a Git Runtime token, and a Git user token. Both the Runtime and user tokens are Git access tokens, used for different purposes in Codefresh.

  • The Git Runtime token is unique to and mandatory for every GitOps Runtime. It must be provided during the Runtime installation.
  • 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.

Git Runtime tokens versus Git user tokens in Codefresh

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

  Git Runtime token Git user token
Usage
  • During installation, to create the Git repository and install the GitOps Runtime.
  • After installation, used by:
    • Argo CD to clone the Git repos, pull changes, and sync to the K8s cluster.
    • 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 Runtime token scopes

The table below lists the scopes required for Git Runtime tokens for the different Git providers.

Git provider Required scopes for Git Runtime token
GitHub and GitHub Enterprise
  • Classic:
    • repo
    • admin:repo_hook
  • Fine-grained:
    • Repository access: All repositories or Only select repositories
    • Repository permissions:
      • Administration: Read and write
      • Contents: Read and write
      • Metadata: Read-only
      • Webhook: Read and write
GitLab Cloud and GitLab Server
  • api
  • read_repository
Bitbucket Cloud and Bitbucket Server
  • Account: Read
  • Workspace membership: Read
  • Webhooks: Read and write
  • Repositories: Write, Admin

Git user access token scopes

The table below lists the scopes required for Git user access tokens for the different Git providers.

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

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.

Managing Git PATs
User settings