Azure DevOps Search

Description

The Azure DevOps Search SCM plugin allows you to interact with multiple Azure DevOps repositories at once — either by fetching files or by pushing updates to them. Repositories are discovered dynamically using regex patterns for project name, repository name, and branch name.

condition

When used in a condition, the SCM block typically fetches files or metadata from the matching repositories.

target

When used in a target, the SCM block pushes changes to all matching repositories.

By default, the Azure DevOps Search SCM uses a working branch workflow: it creates a temporary branch, commits the changes, and opens a pull request targeting the branch defined in the configuration for each matching repository.

Parameters

Name	Type	Description
branch	string	“branch” defines the git branch regex to work on.
commitmessage	object	“commitMessage” is used to generate the final commit message.
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.
directory	string	“directory” defines the local path where the git repository is cloned.
email	string	“email” defines the email used to commit changes.
force	boolean	“force” is used during the git push phase to run `git push --force`.
gpg	object	“gpg” specifies the GPG key and passphrase used for commit signing.
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`
limit	integer	Limit defines the maximum number of repositories to return.
organization	string	“organization” defines the Azure DevOps organization.
project	string	“project” defines the Azure DevOps project regex used to match projects to search in.
repository	string	“repository” defines the Azure DevOps repository regex used to match repositories.
submodules	boolean	“submodules” defines if Updatecli should checkout submodules.
token	string	“token” specifies the personal access token used to authenticate with Azure DevOps.
url	string	“url” defines the Azure DevOps base URL.
user	string	“user” specifies the user associated with new git commit messages created by Updatecli.
username	string	“username” specifies the username used for git authentication.
workingbranch	boolean	“workingBranch” defines if Updatecli should use a temporary branch to work on.
workingbranchprefix	string	WorkingBranchPrefix defines the prefix used to create a working branch.
workingbranchseparator	string	WorkingBranchSeparator defines the separator used to create a working branch.

Authentication

Updatecli supports Personal Access Token (PAT) authentication for interacting with Azure DevOps. You can authenticate using environment variables or directly in your manifest.

1. Personal Access Token via Environment Variables

Set the following environment variables to enable PAT authentication:

UPDATECLI_AZURE_DEVOPS_TOKEN: Your Azure DevOps Personal Access Token
UPDATECLI_AZURE_DEVOPS_USERNAME: Your Azure DevOps username

Example:

export UPDATECLI_AZURE_DEVOPS_TOKEN="your-pat-token"
export UPDATECLI_AZURE_DEVOPS_USERNAME="your-username"

Note	When these variables are set, Updatecli will use them for all Azure DevOps operations.

2. Personal Access Token via Manifest

You can specify your Personal Access Token directly in your Updatecli manifest under the spec.token and spec.username fields:

scms:
  default:
    kind: azuredevops
    spec:
      organization: myorg
      project: myproject
      repository: myrepo
      token: "{{ requiredEnv `UPDATECLI_AZURE_DEVOPS_TOKEN` }}"
      username: "{{ requiredEnv `UPDATECLI_AZURE_DEVOPS_USERNAME` }}"

Warning

For security reasons, it is recommended to use environment variables or secret management tools (like SOPS) instead of hardcoding tokens in your manifest.

Precedence and Fallback

Updatecli will use the first valid authentication method it finds, in the following order:

Personal Access Token via environment variables
Personal Access Token via manifest

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

Further Reading

Tip: For best security and maintainability, prefer using 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

This pipeline automatically updates the Golang version across multiple Azure DevOps repositories within the myorg organization. Using the azuredevopssearch SCM, it discovers all repositories within projects and branches matching the configured regex patterns, and opens pull requests that update the Golang version in the build workflows accordingly. All changes are squashed into one commit per repository.

# updatecli.yaml
name: "Updatecli Golang - Azure DevOps Multi-Repo"
pipelineid: "golang/version"

scms:
  default:
    kind: azuredevopssearch
    spec:
      organization: myorg
      project: "^myproject$"
      repository: "^.*$"
      branch: "^main$"
      token: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_TOKEN" }}'
      username: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_USERNAME" }}'
      user: updatecli
      email: updatecli@example.com
      commitmessage:
        squash: true
        type: chore
        scope: deps
        title: "update Golang version"

actions:
  default:
    kind: azuredevops/pullrequest
    scmid: default
    spec:
      title: "deps(golang): Bump Golang version"

sources:
  golang:
    name: Get the latest Golang version
    kind: golang
    spec:
      versionfilter:
        kind: semver
        pattern: "1.24.x"

targets:
  github-action:
    name: 'deps(github-action): Bump Golang version to {{ source "golang" }}'
    kind: yaml
    scmid: default
    spec:
      engine: yamlpath
      files:
        - ".github/workflows/*"
      key: '$.jobs.build.steps[?(@.uses =~ /^actions\/setup-go/)].with.go-version'
      searchpattern: true