Github

Description

The github scm plugin clones a GitHub repository locally so that other resources can read from it, and pushes changes back to it. It is referenced by a resource through its scmid, as described on the "SCM" page.

Its behavior depends on the stage referencing it:

source and condition: The repository is cloned and the resource works on the files from the branch defined by branch. Nothing is pushed.
target: Updatecli creates a working branch based on branch, commits the changes to it, and pushes that branch to the remote. The branch value itself is never modified.

Important

This plugin does not open pull requests. Pushing a working branch and opening a pull request are two distinct steps: the pull request is created by an actions block of kind github/pullrequest, documented on the "GitHub Pull Request" page. Without such an action, the working branch is pushed and nothing else happens.

If you only need to read from GitHub without cloning a repository (for instance the latest release of a project), use a resource such as githubrelease instead of an scm.

Requirements

A GitHub credential is required, including for public repositories. The scm authenticates every git operation, so without a usable credential the pipeline fails at clone time with:

failed to get access token: no access token found

See Authentication below for the accepted credentials and the order in which they are tried.

The credential needs read access to the repository for a source or a condition, and write access to the repository contents for a target. A github/pullrequest action additionally needs permission to open pull requests.

Parameters

Name	Type	Description
app	object	“app” specifies the GitHub App credentials used to authenticate with GitHub API. It is not compatible with the “token” and “username” fields. It is recommended to use the GitHub App authentication method for better security and granular permissions. For more information, please refer to the following documentation: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation
clientid	string	ClientID represents the GitHub App client ID
expirationtime	string	Expiration represents the token expiration time in seconds The token is used during the entire execution of updatecli and should be valid for the entire duration of the run The minimum value is 600 seconds (10 minutes) Default: 3600 (1 hour)
installationid	string	InstallationID represents the GitHub App installation ID It is the same ID that you can find in the GitHub endpoint: https://github.com/settings/installation/
privatekey	string	PrivateKey represents a PEM encoded private key It is recommended to use PrivateKeyPath instead of PrivateKey to avoid putting sensitive information in the configuration file If both PrivateKey and PrivateKeyPath are set, PrivateKey takes precedence
privatekeypath	string	PrivateKeyPath represents the path to a PEM encoded private key If both PrivateKey and PrivateKeyPath are set, PrivateKey takes precedence It is recommended to use an environment variable to set the PrivateKeyPath value e.g. PrivateKeyPath: {{ requiredEnv “GITHUB_APP_PRIVATE_KEY_PATH” }} to avoid putting sensitive information in the configuration file
branch	string	“branch” defines the git branch to work on. compatible: scm default: main remark: depending on which resource references the GitHub scm, the behavior will be different. If the scm is linked to a source or a condition (using scmid), the branch will be used to retrieve file(s) from that branch. If the scm is linked to target then Updatecli creates a new “working branch” based on the branch value. The working branch created by Updatecli looks like “updatecli_”. The working branch can be disabled using the “workingBranch” parameter set to false.
commitmessage	object	“commitMessage” is used to generate the final commit message. compatible: scm remark: it’s worth mentioning that the commit message settings is applied to all targets linked to the same scm.
body	string	body defines the commit body of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
deprecatedtitle	string	DeprecatedTitle is deprecated and will be ignored. The commit title is now always generated from the target name or description.
footers	string	footers defines the footer of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
hidecredit	boolean	hideCredit defines if updatecli credits should be displayed inside commit message body please consider sponsoring the Updatecli project if you want to disable credits. -> https://github.com/updatecli/updatecli default: false
scope	string	scope defines the scope of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: none
squash	boolean	squash defines if the commit should be squashed default: false important: if squash is set to true, then it’s highly recommended to set the commit body to a meaningful value as all other commit information will be lost during the squash operation. if body is not set, then the commit title/message will be generated based on the most recent commit message of the squashed commits. The commit title is always generated from the target name or description.
title	string	Title is the parsed commit message title (not configurable via YAML). The title is automatically generated from the target name or description.
type	string	type defines the type of commit message such as “chore”, “fix”, “feat”, etc. as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: chore
commitusingapi	boolean	“commitUsingApi” defines if Updatecli should use GitHub GraphQL API to create the commit. When set to `true`, a commit created from a GitHub action using the GITHUB_TOKEN will automatically be signed by GitHub. More info on https://github.com/updatecli/updatecli/issues/1914 compatible: scm default: false
depth	integer	Depth defines the depth used when cloning the git repository. Default: disabled (full clone) Remark: When using a shallow clone (depth greater than 0), Updatecli is not able to retrieve the full git history. This may cause some issues when Updatecli tries to push changes to the remote repository. In that case, you may need to set the force option to true to force push changes to the remote repository.
directory	string	“directory” defines the local path where the git repository is cloned. compatible: scm remark: Unless you know what you are doing, it is recommended to use the default value. The reason is that Updatecli may automatically clean up the directory after a pipeline execution. default: The default value is based on your local temporary directory like: (on Linux) /tmp/updatecli/github//
email	string	“email” defines the email used to commit changes. compatible: scm default: default set to your global git configuration
force	boolean	“force” is used during the git push phase to run `git push --force`. compatible: scm default: true remark: When force is set to true, Updatecli also recreates the working branches that diverged from their base branch.
gpg	object	“gpg” specifies the GPG key and passphrased used for commit signing compatible: scm
passphrase	string	passphrase defines the gpg passphrase used to sign the commit message
signingkey	string	signingKey defines the gpg key used to sign the commit message default: none
owner	string	“owner” defines the owner of a repository. compatible: scm
repository	string	“repository” specifies the name of a repository for a specific owner. compatible: scm
submodules	boolean	“submodules” defines if Updatecli should checkout submodules. compatible: scm default: true
token	string	“token” specifies the credential used to authenticate with GitHub API. compatible: scm remark: A token is a sensitive information, it’s recommended to not set this value directly in the configuration file but to use an environment variable or a SOPS file. The value can be set to `{{ requiredEnv "GITHUB_TOKEN"}}` to retrieve the token from the environment variable `GITHUB_TOKEN` or `{{ .github.token }}` to retrieve the token from a SOPS file. For more information, about a SOPS file, please refer to the following documentation: https://github.com/getsops/sops
url	string	“url” specifies the default github url in case of GitHub enterprise compatible: scm default: github.com
user	string	“user” specifies the user associated with new git commit messages created by Updatecli compatible: scm
username	string	“username” specifies the username used to authenticate with GitHub API. compatible: scm remark: the token is usually enough to authenticate with GitHub API. Needed when working with GitHub private repositories.
workingbranch	boolean	“workingBranch” defines if Updatecli should use a temporary branch to work on. If set to `true`, Updatecli create a temporary branch to work on, based on the branch value. compatible: scm default: true
workingbranchprefix	string	WorkingBranchPrefix defines the prefix used to create a working branch. compatible: scm default: updatecli remark: A working branch is composed of three components: WorkingBranchPrefix Target Branch PipelineID If WorkingBranchPrefix is set to ‘’, then the working branch will look like “_”.
workingbranchseparator	string	WorkingBranchSeparator defines the separator used to create a working branch. compatible: scm default: “_”

owner and repository are the only mandatory parameters. Everything else has a default or is optional.

Note	The table above is generated from the Updatecli JSON schema, which is refreshed by a bot after each Updatecli release. A parameter added very recently (currently `singleBranch`, which restricts clone and fetch to the configured branch) may be usable by the binary before it appears here.

Authentication

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:

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:

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.

Branch and working branch

branch is the branch resources read from, and the branch a target’s changes are ultimately meant for. Updatecli never commits directly to it unless you explicitly opt out of the working branch.

For a target, the working branch is derived from three components joined by a separator:

<workingBranchPrefix><workingBranchSeparator><branch><workingBranchSeparator><pipelineID>

With the defaults (workingBranchPrefix: updatecli, workingBranchSeparator: _), a pipeline updating main produces a branch such as updatecli_main_6f3c…. The pipelineID component is a hash derived from the pipeline, so the same pipeline always reuses the same working branch instead of piling up new ones. Characters GitHub does not accept in a ref are stripped or replaced, and the result is truncated to 255 characters.

Setting workingBranchPrefix to an empty string drops the prefix, giving <branch>_<pipelineID>.

Disabling the working branch

Setting workingBranch: false makes Updatecli commit and push directly to branch. Because force defaults to true (meaning git push --force), this combination is refused unless you also set force explicitly:

Better safe than sorry.

Updatecli may be pushing unwanted changes to the branch "main".

Set force: false to push without forcing, or force: true to acknowledge the force push. Note that when force is true, Updatecli also recreates working branches that have diverged from their base branch.

Cleaning up working branches

updatecli apply --clean-git-branches deletes, at the end of the run, every working branch that ended up identical to its base branch - the branches left behind by pipelines that turned out to have nothing to change. Branches carrying actual commits are kept. The flag has no effect on a dry run (updatecli diff) or when pushing is disabled.

Commit message

Updatecli generates conventional commits, to give commit messages a meaning that is readable by both humans and machines. The commitMessage parameters (type, scope, body, footers, hideCredit, squash) shape the generated message.

The commit title is always generated from the target’s name, or from its description when name is unset. The title is capped at 72 characters, minus the room taken by type and scope; anything longer is truncated with an ellipsis and the remainder is moved into the commit body. With the default type chore, this produces:

Author: olblak <updatecli-bot@updatecli.io>
Date:   Tue May 4 15:41:44 2021 +0200

    chore: Update key "dependencies[0].version" from file "charts/jenkins/r...

    ... equirements.yaml"

    Made with ❤️️  by updatecli

Setting body replaces the generated body entirely, including the truncated remainder shown above. hideCredit: true removes the "Made with ❤️️ by updatecli" line.

Warning

commitMessage.title is deprecated and ignored. Rename the target instead - the commit title now always comes from the target name. Updatecli logs a warning when the field is present.

squash: true rewrites the commits added on the working branch into a single commit. Since all intermediate commit information is lost, set body to something meaningful when squashing.

Note	The `commitMessage` settings apply to every target linked to the same scm.

Commit signing

Two independent mechanisms are available.

gpg: signingkey takes an armored private GPG key and passphrase its password. Updatecli signs the commit locally with that key.
commitUsingApi: When set to true, the commit is created through the GitHub GraphQL API rather than by the local git client. GitHub then signs the commit itself with its own key - this is how a workflow running under GITHUB_TOKEN produces a verified commit without managing a GPG key. Updatecli creates the working branch through the API when it does not exist yet, then pulls the resulting commit back into the local clone.

Note	`squash` is not supported together with `commitUsingApi`. The option is ignored and a warning is logged.

Clone behavior

By default the repository is cloned under your system temporary directory, at <tmp>/updatecli/github/<owner>/<repository> - for example /tmp/updatecli/github/updatecli/updatecli on Linux. Overriding directory is rarely useful, as Updatecli may clean that directory up after a run.

Three parameters control how much is fetched, all of them trade-offs on large repositories:

submodules: Defaults to true. Set it to false to skip submodule checkout.
depth: Number of commits to fetch. Unset means a full clone. A shallow clone gives Updatecli an incomplete history, which can break pushes; setting force: true is often necessary alongside it.
singleBranch: Defaults to false, meaning every branch, tag, and ref is fetched. Set it to true to fetch only branch, which is significantly faster on repositories with many refs. In return, Updatecli may fail to notice an already published working branch in some edge cases, and open a duplicate pull request.

GitHub Enterprise

Point url at your instance, for example github.example.com. The scheme is optional and defaults to https://. Updatecli then talks to the GraphQL API at <url>/api/graphql and clones from <url>/<owner>/<repository>.git. Left unset, url defaults to github.com.

API rate limits

Updatecli checks the remaining GitHub API quota before its GraphQL calls. When the limit is exceeded, it pauses until the quota resets and retries, up to three times, before failing the pipeline. Run with --debug to see the quota reported at each call.

Example

Default

# updatecli.yaml
name: Example of a GitHub SCM configuration

scms:
  default:
    kind: github
    spec:
      # owner and repository are the only mandatory parameters
      owner: updatecli
      repository: updatecli
      # branch resources read from, and the base branch of the working branch
      # created for targets
      branch: main
      # credentials, better provided by the UPDATECLI_GITHUB_TOKEN environment
      # variable than by the manifest
      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
      username: '{{ requiredEnv "GITHUB_ACTOR" }}'
      # identity used for the git commits, defaults to updatecli-bot
      user: updatecli-bot
      email: updatecli-bot@updatecli.io

targets:
  # the target name is used as the commit title
  updateChartVersion:
    name: 'deps: bump chart dependency version'
    kind: yaml
    scmid: default
    spec:
      file: charts/jenkins/Chart.yaml
      key: $.version

CommitMessage

# updatecli.yaml
name: Example with a GitHub commit message

scms:
  default:
    kind: github
    spec:
      owner: updatecli
      repository: updatecli
      branch: main
      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
      commitmessage:
        # produces "deps(charts): <target name>"
        type: deps
        scope: charts
        footers: 'Signed-off-by: updatecli-bot <updatecli-bot@updatecli.io>'
        # remove the "Made with ❤️ by updatecli" line from the commit body
        hidecredit: true
        # squash every commit of the working branch into one, using the body below
        squash: true
        body: |
          This commit was generated by Updatecli.

targets:
  # the commit title comes from this name, "commitmessage.title" is deprecated
  updateChartVersion:
    name: 'bump chart dependency version'
    kind: yaml
    scmid: default
    spec:
      file: charts/jenkins/Chart.yaml
      key: $.version

GitHub App

# updatecli.yaml
name: Example of a GitHub SCM authenticated with a GitHub App

scms:
  default:
    kind: github
    spec:
      owner: updatecli
      repository: updatecli
      branch: main
      # "app" and "token" are mutually exclusive
      app:
        clientid: '{{ requiredEnv "GITHUB_APP_CLIENT_ID" }}'
        installationid: '{{ requiredEnv "GITHUB_APP_INSTALLATION_ID" }}'
        # privatekey and privatekeypath are both accepted,
        # privatekey takes precedence when both are set
        privatekeypath: '{{ requiredEnv "GITHUB_APP_PRIVATE_KEY_PATH" }}'
        # token lifetime in seconds, 3600 by default, 600 minimum
        expirationtime: "3600"

targets:
  updateChartVersion:
    name: 'deps: bump chart dependency version'
    kind: yaml
    scmid: default
    spec:
      file: charts/jenkins/Chart.yaml
      key: $.version

Last updated on July 30, 2026

Amazon AMI

Configuration

Docs

Title here

Github

Description

Requirements

Parameters

Authentication

Branch and working branch

Disabling the working branch

Cleaning up working branches

Commit message

Commit signing

Clone behavior

GitHub Enterprise

API rate limits

Example

Default

CommitMessage

GitHub App

Github

Description#

Requirements#

Parameters#

Authentication#

Branch and working branch#

Disabling the working branch#

Cleaning up working branches#

Commit message#

Commit signing#

Clone behavior#

GitHub Enterprise#

API rate limits#

Example#

Default#

CommitMessage#

GitHub App#

Description

Requirements

Parameters

Authentication

Branch and working branch

Disabling the working branch

Cleaning up working branches

Commit message

Commit signing

Clone behavior

GitHub Enterprise

API rate limits

Example

Default

CommitMessage

GitHub App