# <no value>
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:

[source,shell]
----
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:

[source,shell]
----
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:

[source,shell]
----
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:

[source,yaml]
----
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:

[source,yaml]
----
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:

[source,yaml]
----
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:

. `UPDATECLI_GITHUB_TOKEN` environment variable
. `UPDATECLI_GITHUB_APP_*` environment variables
. `spec.token` in the manifest
. `spec.app` in the manifest
. `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:

[source,text]
----
failed to get access token: no access token found
----

'''

*Further Reading*

- https://docs.github.com/en/developers/apps[GitHub App Documentation]
- https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token[Creating a Personal Access Token]
- https://www.updatecli.io/docs/plugins/scm/github/#authentication[Updatecli GitHub SCM Plugin Documentation]

'''

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