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

NameTypeDescriptionRequired
branchstring

“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.

commitmessageobject

“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.
    bodystring

“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
    footersstring

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
    hidecreditboolean

“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
    scopestring

“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
    titlestring

“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.
    typestring

“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
commitusingapiboolean

“commitUsingApi” defines if Updatecli should use GitHub GraphQL API to create the commit.

compatible: * scm

default: false

directorystring

“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//

emailstring

“email” defines the email used to commit changes.

compatible:

  • scm

default: default set to your global git configuration

forceboolean

“force” is used during the git push phase to run git push --force.

compatible:
  • scm
default:

false

remark: When force is set to true, Updatecli also recreates the working branches that diverged from their base branch.

gpgobject

“gpg” specifies the GPG key and passphrased used for commit signing

compatible:

  • scm
    passphrasestringpassphrase defines the gpg passphrase used to sign the commit message
    signingkeystring

signingKey defines the gpg key used to sign the commit message

	default:
		none
ownerstring

“owner” defines the owner of a repository.

compatible:

  • scm
repositorystring

“repository” specifies the name of a repository for a specific owner.

compatible:

  • scm
submodulesboolean

“submodules” defines if Updatecli should checkout submodules.

compatible: * scm

default: true

tokenstring

“token” specifies the credential used to authenticate with GitHub API.

compatible:
	* scm
urlstring

“url” specifies the default github url in case of GitHub enterprise

compatible:

  • scm

default: github.com

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

userstring

“user” specifies the user associated with new git commit messages created by Updatecli

compatible:

  • scm
usernamestring

“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.

workingbranchboolean

“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

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"
Top