Docs

Updatecli supports multiple authentication methods for interacting with GitHub. You can authenticate using either a Personal Access Token (PAT) or a GitHub App. Below are the supported methods; the order in which Updatecli picks one is described under Precedence and Fallback at the end of this section.

1. GitHub App Authentication via Environment Variables

Set the following environment variables to enable GitHub App authentication:

  • UPDATECLI_GITHUB_APP_CLIENT_ID: Your GitHub App’s Client ID

  • UPDATECLI_GITHUB_APP_PRIVATE_KEY: The private key for your GitHub App (PEM format, as a string)

  • UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH: The path to your GitHub App’s private key file (PEM format)

  • UPDATECLI_GITHUB_APP_INSTALLATION_ID: The installation ID for your GitHub App

  • UPDATECLI_GITHUB_APP_EXPIRATION_TIME: Optional token lifetime in seconds. Defaults to 3600 (one hour), the minimum accepted value is 600

You can use either UPDATECLI_GITHUB_APP_PRIVATE_KEY or UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH to provide the private key.

Example using the private key content:

export UPDATECLI_GITHUB_APP_CLIENT_ID="123456"
export UPDATECLI_GITHUB_APP_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
export UPDATECLI_GITHUB_APP_INSTALLATION_ID="789012"

Example using the private key path:

export UPDATECLI_GITHUB_APP_CLIENT_ID="123456"
export UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH="/path/to/private-key.pem"
export UPDATECLI_GITHUB_APP_INSTALLATION_ID="789012"
Note

When these variables are set and UPDATECLI_GITHUB_TOKEN is not, Updatecli uses GitHub App authentication for all GitHub operations, ignoring any credential set in the manifest.

If the four variables do not form a valid configuration (a missing private key, an installation ID that is not an integer, an expiration below 600 seconds), the whole set is silently ignored and Updatecli moves on to the next method. Run with --debug to see which credential was selected.

2. Personal Access Token via Environment Variable

Set the following environment variable to use a Personal Access Token:

  • UPDATECLI_GITHUB_TOKEN: Your GitHub Personal Access Token

  • UPDATECLI_GITHUB_USERNAME: Your GitHub username. Optional; Updatecli uses oauth2 when it is unset.

Example:

export UPDATECLI_GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

This is the credential Updatecli looks at first. When it is set, every other method below is ignored, including the ones declared in the manifest.

3. Personal Access Token via Manifest

You can specify your Personal Access Token directly in your Updatecli manifest under the spec.token field:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      token: "{{ requiredEnv `GITHUB_TOKEN` }}"
Warning

For security reasons, it is recommended to use environment variables or secret management tools (like SOPS) instead of hardcoding tokens in your manifest.

4. GitHub App Authentication via Manifest

You can configure GitHub App authentication directly in your manifest using the spec.app field:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      app:
        clientID: "123456"
        privateKey: "{{ requiredEnv `GITHUB_APP_PRIVATE_KEY` }}"
        installationID: "789012"

Or, if you prefer to reference a private key file:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      app:
        clientID: "123456"
        privateKeyPath: "/path/to/private-key.pem"
        installationID: "789012"

Precedence and Fallback

Updatecli uses the first credential it finds, in the following order:

  1. UPDATECLI_GITHUB_TOKEN environment variable

  2. UPDATECLI_GITHUB_APP_* environment variables

  3. spec.token in the manifest

  4. spec.app in the manifest

  5. GITHUB_TOKEN environment variable

The environment always wins over the manifest: a spec.token is dead weight as soon as UPDATECLI_GITHUB_TOKEN is exported, which is a common surprise when a manifest behaves differently on a workstation and in CI.

GITHUB_TOKEN is a last-resort fallback, meant for GitHub Actions where the runner exports it automatically. It is only consulted once every other method has come up empty.

Warning

spec.token and spec.app cannot be combined in the same manifest. Doing so fails at load time with you cannot use both token and app authentication methods.

If no credential is found at all, Updatecli builds an unauthenticated GraphQL client instead of stopping immediately. Read-only resources may still work against public repositories, but every scm operation fails as soon as it needs the credential:

failed to get access token: no access token found

Further Reading

Tip: For best security and maintainability, prefer using a GitHub App or environment variables for authentication, and avoid hardcoding secrets in your manifests.

Last updated on July 30, 2026
Prev
Next