Docs

Scm

Description

An scm configuration provides the git repository information used by a source, a condition, a target, an action, or autodiscovery.

When an updatecli pipeline is triggered, the first thing updatecli does, is clone all referenced git repositories into a temporary directory. Resources referencing that scm through their scmid key then operate on the clone rather than on the current working directory, and a target that changes a file there gets its change committed and pushed to a branch named after the pipeline pipelineid.

A resource without an scmid simply works on the current working directory, and Updatecli neither clones nor commits anything for it.

The local scm

local is a reserved scm identifier. Referencing scmid: local from a resource or an action, without declaring scms.local yourself, asks Updatecli to auto-detect the git repository of the current directory: its root, its remote, and its branch. This is how you commit changes to the repository you are already in, rather than to a clone.

Declaring scms.local explicitly overrides that detection, and setting disabled: true on it opts out of the auto-detection entirely.

targets:
  version:
    kind: file
    # Commit the change to the repository Updatecli runs in
    scmid: local
    spec:
      file: VERSION

Parameters

NameTypeDescriptionRequired
disabledboolean
kindstringkind specifies the scms resource kind
specobjectspec specifies parameters for a specific scms kind

Searching for repositories

Three scm kinds do not describe a single repository but a search query: githubsearch, gitlabsearch, and azuredevopssearch. Updatecli resolves the query while loading the manifest and duplicates the whole pipeline once per discovered repository, which is how a single manifest can be applied across an organization.

Important
A search returning no repository is an error, not an empty run: Updatecli would otherwise not know how to handle the remaining configuration.

Examples

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
Prev
Docker Digest
Next
Transformer