Github

kind: github

Description

Depending on the situation a specific SCM block can be provided to manipulate information from a Github SCM repository by either fetching files from a repository or pushing files to them

condition

When the SCM block is used in a condition, it usually means fetching a file from that repository.

target

When the SCM block is used in a target, it usually means pushing a file to that repository.

It’s important to notice that the Github SCM implements the Github workflow and therefore will push changes to a temporary branch then open a pull request targeting the branch defined in the configuration.

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
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 title and body to a meaningful value as all other commit information will be lost during the squash operation. if title and body are not set, then the commit title/message will be generated based on the most recent commit message of the squashed commits.
title	string	title defines the title of the commit message as defined by the conventional commit specification. More information on -> https://www.conventionalcommits.org/en/ default: default is set to the target name or the target short description if the name is not defined.
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
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: “_”

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, in order of precedence.

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

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, Updatecli will use GitHub App authentication for all GitHub operations.

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, if required by certain operations like scm operation.

Example:

export UPDATECLI_GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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 will use the first valid authentication method it finds, in the following order:

Personal Access Token via environment variable
GitHub App via environment variables
Personal Access Token via manifest
GitHub App via manifest

If no valid authentication is found, Updatecli will fail with an error.

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.

CommitMessage

Updatecli uses conventional commits as describe on www.conventionnalcommits.org.
The goal is to add human and machine readable meaning to commit messages

By default, Updatecli generates a commit message using the default type "chore" and split long title message into the body like:

Author: olblak <updatecli@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

Example

Default

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

scms:
  default:
    kind: github
    spec:
      user: "git user to push from changes"
      email: "git user email to push from change"
      directory: "directory where to clone the git repository"
      owner: "github owner"
      repository: "github repository"
      token: "github token with enough permission on repository"
      username: "github username used for push git changes. Needed in private repositories"
      branch: "git branch where to push changes"

targets:
  id:
    kind: yaml
    scmid: default
    spec:
      file: "Yaml file path from the root repository"
      key: "yaml key to update"

CommitMessage

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

scms:
  default:
    kind: github
    spec:
      user: "git user to push from changes"
      email: "git user email to push from change"
      directory: "directory where to clone the git repository"
      owner: "github owner"
      repository: "github repository"
      token: "github token with enough permission on repository"
      username: "github username used for push git changes"
      branch: "git branch where to push changes"
      commitmessage:
        type: "feat"
        title: "Override default commit title"

targets:
  id:
    kind: yaml
    scmid: default
    spec:
      file: "Yaml file path from the root repository"
      key: "yaml key to update"

Last modified on October 17, 2025

Edit this page on GitHub