Updatecli
Docs

Git

Description

The git scm plugin clones a git repository from any URL and pushes changes back to it. It knows nothing about the hosting platform, which makes it the fallback for servers Updatecli has no dedicated plugin for. 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

The changes are committed and pushed. By default they go straight to branch, because workingBranch defaults to false on this plugin. See Working branch to commit to a dedicated branch instead.

Note

Prefer the dedicated plugin when one exists - GitHub, GitLab, Gitea, Bitbucket, Stash, Azure DevOps. They default to a working branch and can be paired with an action that opens a pull request. The git plugin can only push; no pull request will ever be opened from it.

Parameters

NameTypeDescriptionRequired
branchstring

“branch” defines the git branch to work on.

default: main

remark:

  • when the git scm is used by a source or a condition, files are read from this branch.
  • when the git scm is used by a target, Updatecli pushes changes to this branch, or to a working branch based on it when “workingbranch” is true.
  • see https://github.com/updatecli/updatecli/issues/1139

example:

  • branch: main
commitmessageobject

“commitmessage” defines the settings used to generate commit messages.

remark:

  • the settings apply to every target using this scm.
    bodystring

“body” defines the conventional commit body.

default: empty, which means the body is generated by Updatecli.

remark:

  • see https://www.conventionalcommits.org/en/
    deprecatedtitlestring

“title” is ignored.

deprecated:

  • the commit title is always generated from the target name or description.
    footersstring

“footers” defines the conventional commit footers.

default: empty

remark:

  • see https://www.conventionalcommits.org/en/
    hidecreditboolean

“hidecredit” defines whether the Updatecli credit line is left out of the commit message body.

default: false

remark:

  • if you disable the credit line, please consider sponsoring the Updatecli project, https://github.com/updatecli/updatecli
    scopestring

“scope” defines the conventional commit scope.

default: empty

remark:

  • see https://www.conventionalcommits.org/en/
    squashboolean

“squash” defines whether the commits are squashed into a single commit.

default: false

remark:

  • squashing loses the other commit messages, so setting a meaningful “body” is recommended.
  • when “body” is empty, the squashed commit message is generated from the most recent squashed commit. The title is always generated from the target name or description.
    titlestringTitle is the parsed commit message title (not configurable via YAML). The title is automatically generated from the target name or description.
    typestring

“type” defines the conventional commit type, such as “chore”, “fix” or “feat”.

default: chore

remark:

  • see https://www.conventionalcommits.org/en/
depthinteger

“depth” defines the depth used when cloning the git repository.

default: empty, which means a full clone.

remark:

  • a value greater than 0 creates a shallow clone, so Updatecli cannot see the full git history. Pushing changes may then fail, in which case setting “force” to true may be needed.
  • a negative value is rejected.

example:

  • depth: 1
directorystring

“directory” defines the local path where the git repository is cloned.

default: a directory under the Updatecli temporary directory, such as “/tmp/updatecli/” on Linux.

remark:

  • keep the default value unless you have a good reason to change it, as Updatecli may delete the directory after a pipeline run.
emailstring

“email” defines the email address used to author commits.

default: updatecli-bot@updatecli.io

forceboolean

“force” defines whether Updatecli runs git push --force when pushing changes.

default: false

remark:

  • when true, Updatecli also recreates the working branches that diverged from their base branch.
  • when “force” is true and “workingbranch” is not set, the git scm returns an error, to avoid force pushing to “branch” by mistake. Set “workingbranch” explicitly to confirm the behavior.
gpgobject“gpg” defines the GPG key and passphrase used to sign commits.
    passphrasestring“passphrase” defines the passphrase that unlocks “signingkey”.
    signingkeystring

“signingkey” defines the armored GPG private key used to sign commits.

default: empty, which means commits are not signed.

remark:

  • the value is the key content, not a key ID.
  • a private key is sensitive, so avoid writing it in the manifest.
passwordstring

“password” defines the password used to authenticate over HTTP.

remark:

  • a password is sensitive, so avoid writing it in the manifest. Read it from an environment variable, for example with {{ requiredEnv "GIT_PASSWORD" }}.
singlebranchboolean

“singlebranch” defines whether Updatecli clones and fetches only the configured branch, instead of every branch, tag and other reference of the remote.

default: false

remark:

  • enabling it can make operations much faster on repositories with many branches, tags or other references, because Updatecli skips the fetch that mirrors every remote reference.
  • in some edge cases, Updatecli may then miss a working branch that was already pushed, and open a duplicate pull request.
submodulesboolean

“submodules” defines whether Updatecli clones the git submodules of the repository.

default: true

urlstring

“url” defines the URL of the git repository.

remark:

  • with the ssh protocol, the local ssh configuration must allow cloning the repository.

example:

  • url: git@github.com:updatecli/updatecli.git
  • url: https://github.com/updatecli/updatecli.git
userstring

“user” defines the name used to author commits.

default: updatecli-bot

usernamestring“username” defines the username used to authenticate over HTTP.
workingbranchboolean

“workingbranch” defines whether Updatecli pushes changes to a temporary working branch based on “branch”, instead of pushing to “branch” directly.

default: false

workingbranchprefixstring

“workingbranchprefix” defines the prefix of the working branch name.

default: updatecli

remark:

  • the working branch name joins the prefix, the target branch and the pipeline ID, separated by “workingbranchseparator”.
  • when set to an empty string, the name starts with the separator, for example “main”.
workingbranchseparatorstring

“workingbranchseparator” defines the separator between the parts of the working branch name.

default: _

url is the only mandatory parameter. It accepts both protocols:

url: "https://github.com/updatecli/updatecli.git"   # HTTP(S)
url: "git@github.com:updatecli/updatecli.git"       # SSH
Note
The table above is generated from the Updatecli JSON schema, refreshed by a bot after each release. A recently added parameter (currently singleBranch, which restricts clone and fetch to the configured branch) may work in the binary before it shows up here.

Authentication

How Updatecli authenticates follows from the URL scheme.

HTTP(S)

username and password are sent as HTTP basic credentials. On most platforms the "password" is a personal access token rather than an account password, and the username can be any non-empty value. Keep them out of the manifest itself:

username: '{{ requiredEnv "GIT_USERNAME" }}'
password: '{{ requiredEnv "GIT_TOKEN" }}'
SSH

username and password are ignored. Updatecli relies on your local ssh-agent, so the key must already be loaded (ssh-add -l should list it) and the agent reachable through SSH_AUTH_SOCK. There is no parameter to point at a private key file.

Anonymous access works for public repositories over HTTPS when both fields are left empty, which is enough for a source or a condition.

Working branch

Unlike the platform-specific plugins, git commits directly to branch unless you opt in. Setting workingBranch: true makes Updatecli create a dedicated branch instead:

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

With the defaults (updatecli and ), a pipeline based on main produces updatecli_main<pipelineID>, where pipelineID is a hash derived from the manifest, so the same pipeline reuses the same branch instead of piling up new ones. Characters git refuses in a ref are stripped, and the name is truncated to 255 characters. Setting workingBranchPrefix: "" gives <branch>_<pipelineID>.

branch itself defaults to main.

Force push

force runs git push --force, and also makes Updatecli recreate working branches that diverged from their base branch. It defaults to false here.

Because force-pushing straight onto a shared branch is destructive, and because some targets (the shell one, for instance) stage every change in the working tree, combining force: true with an unset workingBranch is refused:

Better safe than sorry.

The scm force option set to true means that Updatecli is going to run "git push --force"

Set workingBranch explicitly (to true to force-push a dedicated branch, or to false to confirm you really mean the shared one).

Commit message

Updatecli generates conventional commits. The commitMessage parameters (type, scope, body, footers, hideCredit, squash) shape the result.

The commit title always comes from the target’s name, or from its description when name is unset. It is capped at 72 characters minus the room taken by type and scope; the overflow is moved into the body. With the default type chore:

Author: updatecli-bot <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 that overflow. hideCredit: true drops the credit line. squash: true collapses the commits added on the working branch into one (set body when you use it, since the individual messages are lost).

Warning

commitMessage.title is deprecated and ignored. Rename the target instead; Updatecli logs a warning when the field is present.

Note
commitMessage applies to every target linked to the same scm.

Commit signing

gpg.signingkey takes an armored private GPG key (not the public half) and gpg.passphrase its passphrase. Both are secrets and belong in an environment variable or a SOPS file:

gpg:
  signingkey: '{{ requiredEnv "GPG_SIGNING_KEY" }}'
  passphrase: '{{ requiredEnv "GPG_PASSPHRASE" }}'

Clone behavior

Left unset, directory is derived from the URL under your system temporary directory - /tmp/updatecli/github_com_updatecli_updatecli_git on Linux for https://github.com/updatecli/updatecli.git, with the protocol dropped and separators replaced. Overriding it is rarely useful, as Updatecli may clean that directory up after a run.

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 leaves Updatecli with an incomplete history, which can break pushes; force: true is often needed alongside.

singleBranch

Defaults to false, meaning every branch, tag, and ref is fetched. Setting it to true fetches only branch, which is much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch.

On a repository with a large number of refs, singleBranch is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when branch is set. See Large repositories for a full manifest.

Commit identity

user and email name the commit author, defaulting to updatecli-bot and updatecli-bot@updatecli.io.

Example

Default

The manifest below uses three separate scms: one to read a file, one to test a condition, and one over SSH to push a change on a working branch.

# updatecli.yaml
name: "Example with Git SCM"

scms:
  # HTTP(S) authentication, the password is usually a personal access token
  scenario-source:
    kind: git
    spec:
      url: "https://github.com/updatecli/experiment.git"
      branch: "main"
      username: '{{ requiredEnv "GIT_USERNAME" }}'
      password: '{{ requiredEnv "GIT_TOKEN" }}'

  # anonymous access, enough to read from a public repository
  scenario-condition:
    kind: git
    spec:
      url: "https://github.com/updatecli/updatecli.git"
      branch: "main"

  # SSH authentication, the key is provided by the local ssh-agent
  scenario-target:
    kind: git
    spec:
      url: "git@github.com:updatecli/updatecli.git"
      branch: "main"
      user: "updatecli-bot"
      email: "updatecli-bot@updatecli.io"
      # commit to a dedicated branch instead of pushing straight to "main"
      workingbranch: true
      commitmessage:
        type: "chore"
        scope: "deps"
      # signingkey expects the armored *private* key
      gpg:
        signingkey: '{{ requiredEnv "GPG_SIGNING_KEY" }}'
        passphrase: '{{ requiredEnv "GPG_PASSPHRASE" }}'

sources:
  source-1:
    name: "Source 1"
    kind: file
    scmid: scenario-source
    spec:
      file: README.md

conditions:
  condition-1:
    name: "Condition 1"
    kind: file
    scmid: scenario-condition
    spec:
      file: README.md

targets:
  target-1:
    name: "Target 1"
    kind: file
    scmid: scenario-target
    spec:
      file: README.md

Large repositories

# updatecli.yaml
name: "Example with Git SCM optimized for large repositories"

scms:
  scenario-target:
    kind: git
    spec:
      url: "git@github.com:updatecli/updatecli.git"
      branch: "main"
      singleBranch: true
      user: "git user to push from changes"
      email: "git user email to push from change"

targets:
  target-1:
    name: "Target 1"
    kind: file
    scmid: scenario-target
    spec:
      file: README.md
Last updated on August 6, 2026
Prev
Github Pull Request