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

Name	Type	Description
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 will push any changes to that branch For more information, please refer to the following issue: https://github.com/updatecli/updatecli/issues/1139
commitmessage	object	“commitMessage” is used to generate the final commit message. compatible: * scm remark: it’s worth mentioning that the commit message is applied to all targets linked to the same scm. default: false
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
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 highly 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 /tmp/updatecli/ on Linux
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: false remark: When force is set to true, Updatecli also recreate 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
password	string	“password” specifies the password when using the HTTP protocol compatible: * scm
submodules	boolean	“submodules” defines if Updatecli should checkout submodules. compatible: * scm default: true
url	string	“url” specifies the git url to work on. compatible: * scm example: * git@github.com:updatecli/updatecli.git * https://github.com/updatecli/updatecli.git remarks: when using the ssh protocol, the user must have the right to clone the repository based on its local ssh configuration
user	string	“user” specifies the user associated with new git commit messages created by Updatecli compatible: * scm
username	string	“username” specifies the username when using the HTTP protocol compatible * scm
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: false
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: “_”

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.

Commit identity

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

Example

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

Last updated on July 30, 2026

Github Pull Request

Docs

Title here

Git

Description

Parameters

Authentication

Working branch

Force push

Commit message

Commit signing

Clone behavior

Commit identity

Example

Git

Description#

Parameters#

Authentication#

Working branch#

Force push#

Commit message#

Commit signing#

Clone behavior#

Commit identity#

Example#

Description

Parameters

Authentication

Working branch

Force push

Commit message

Commit signing

Clone behavior

Commit identity

Example