Azure DevOps guides · Documentation index · CLI usage
Set up one classic or release-led versioning pipeline in your own Azure Repos repository. Reviewed modes use the same adapter as their base flow; review is enforced through PR policies, not a second pipeline.
Configuring an existing pipeline? Use the copy block below, then check its YAML identity and permissions. Skip bootstrap if your repository already has release history. For a fresh repository, follow steps 1–7 or one complete walkthrough.
Destination: Azure DevOps → Pipelines → your pipeline → Edit → Variables → New variable → BOT_GPG_SECRETKEY → enable “Keep this value secret”. Use an existing dedicated automation signing key, not your personal key. Select its long ID or full fingerprint from the first command and replace YOUR_GPG_KEY_ID before running the second:
gpg --list-secret-keys --keyid-format=long
gpg --export-secret-key -a YOUR_GPG_KEY_ID # → BOT_GPG_SECRETKEY (secret pipeline variable)Paste the entire armored private-key block with its original line breaks into BOT_GPG_SECRETKEY. If the pipeline does not exist yet, run this block after creating it. Do not save an export file. No SSH key, PAT, or bot user is needed on Azure.
The template has no passphrase input: use only an approved key that can sign unattended without one. Never log the key, enable tracing around it, or paste it into YAML/chat. Multiline-secret masking does not reliably hide individual lines. Already configured the key? No need to recreate it or register it on a hosting account. Need a new key?
- Install Git, Python 3.12, uv, GnuPG, and git-tools. Keep its source checkout: installation is editable.
- Use your own name/email for human commits, your own Azure organization/project/repository for the application origin, and a dedicated automation identity for signing.
YOUR_GIT_TOOLS_SOURCE_URLmeans the upstream tool source, not your application origin; retain the supplied template's upstream clone URL or copy it from the git-tools source repository Code button. - These adapters use
masteranddevelop. You need permission to configure Pipelines and repository security, or an administrator's help. - In Organization settings → Pipelines → Settings or Project settings → Pipelines → Settings, enable Limit job authorization scope to current project for non-release pipelines. YAML pipelines are non-release pipelines even when managing Git release branches. This selects the project Build Service identity used below; organization-level enforcement cannot be relaxed by a project.
- Versioning CI needs no LLM key, Azure bot user, SSH key, or PAT. Checkout/push use Azure's automatic Build Service job token. Local AI commit/PR generation separately needs a configured provider.
Work in your application repository, not the git-tools source checkout. Initialize a fresh repository on master if needed:
git init -b masterCopy one example from your retained upstream checkout into the application, removing .example:
| Flow | Source in git-tools | Destination in your application |
|---|---|---|
| Classic / Classic — Reviewed | Classic example | .azure/workflows/version-bump-git-flow-classic.yml |
| Release-led / Release-led — Reviewed | Release-led example | .azure/workflows/version-bump-git-flow-variant-release-led.yml |
The steps below use classic filenames. Substitute the release-led filename when choosing that flow. Do not activate both adapters for the same branches.
Set GIT_TOOLS_REPO in the copied YAML to that upstream clone URL (the supplied template already has one) and select a supported engine branch or tag:
GIT_TOOLS_REPO: YOUR_GIT_TOOLS_SOURCE_URL # Upstream tool source, not your application origin.
GIT_TOOLS_REF: developVerify that the selected ref contains Azure Merged PR <id>: normalization for fixed workflow-title recognition, your classic/variant strategy, and git_tools.generators.publish. The PR-ID caveat still applies to ordinary squash subjects. Prefer an immutable supported tag for reproducibility. The example uses git clone --branch, so a bare commit SHA is not supported. Installing a newer local CLI does not update this remote CI clone.
Replace these values with your own automation name and email, matching the GPG identity selected in step 2. They need not represent an Azure user account:
GIT_BOT_NAME: YOUR_AUTOMATION_NAME
GIT_BOT_EMAIL: YOUR_AUTOMATION_EMAILKeep full history, tag fetching, and persistCredentials: true. Set GIT_TOOLS_BUMP_SYNC_AUXILIARY to 'true' to sync supported auxiliary version files, or 'false' for .cz.toml only. git-tools init creates version configuration; it does not install or authorize a pipeline.
Already have a suitable automation key? Skip creation and use the copy block above when setting the pipeline secret. It prints the existing key; it does not create or replace one.
Only if you do not have an approved automation key, run this locally:
gpg --full-generate-keyAt the prompts:
- Choose a key type that supports signing (for example RSA and RSA). An RSA size of 3072 bits is a reasonable starting point if your policy allows it.
- Set an expiration matching your organization's rotation policy.
- Enter your own dedicated automation name/email, matching YAML
GIT_BOT_NAMEandGIT_BOT_EMAIL, not the upstream author or your personal signing identity. - The template has no passphrase input. Only under an approved unattended-key policy, leave the new automation key's passphrase empty and confirm any GnuPG warning. If policy requires a protected key, stop and adapt noninteractive signing securely instead; importing it alone does not unlock signing. Do not remove a personal key's passphrase.
Then return to the same list/export copy block, select the new automation key, and paste its printed private block into BOT_GPG_SECRETKEY after the pipeline exists. Azure needs no GitHub-style public-key registration or SSH key for this pipeline. Plan expiration, rotation, revocation, and approved backup storage. Use a trusted, unrecorded terminal and clear clipboard history where practical; no export file or Secure File upload is needed.
Steps 3–7 bootstrap a fresh repository: push once, create/configure the pipeline, run it manually, then create develop from the stable bot commit. Do not repeat bootstrap to repair a failure.
An empty Azure Repo has no branch or YAML for the pipeline picker. In your application repository, replace the origin URL with your own Azure organization, project, and repository. Configure your own human Git name/email, not the automation identity:
git config user.name "YOUR_NAME"
git config user.email "YOUR_EMAIL"
git remote add origin "https://dev.azure.com/YOUR_ORG/YOUR_PROJECT/_git/YOUR_REPOSITORY"
git-tools init --version 0.0.1 --tag-format '$version'If pyproject.toml contains [project].version, initialize it to 0.0.1 too. Review what you are staging; no credentials belong in this commit:
git add -A
git diff --cached
git commit -m "Release 0.1.0"
git push -u origin masterSet the Azure repository's default branch to master after this push. Keep Release 0.1.0 as the latest subject until bootstrap runs. The engine also accepts Release 0.0.1, but the documented sequence uses Release 0.1.0 to produce stable 0.1.0 from the 0.0.1 seed.
- Open Pipelines → New pipeline → Azure Repos Git and select your application repository.
- Choose Existing Azure Pipelines YAML file, branch master, and
/.azure/workflows/version-bump-git-flow-classic.yml(or the release-led file). - Save without running. Give it a recognizable name such as
<your-repo>-version-bump-classicor<your-repo>-version-bump-release-led.
Create a separate pipeline definition for each repository, with only one active versioning adapter per set of branches.
In the saved pipeline, open Edit → Variables → New variable:
- Name:
BOT_GPG_SECRETKEY - Value: the complete armored private key printed by the list/export commands.
- Enable Keep this value secret, leave queue-time override disabled, and save.
Preserve the original multiline block. Do not add quotes, flatten it, or replace real newlines with literal \n. Azure does not repair multiline formatting; these examples use Bash on ubuntu-latest.
The template maps this secret into the import step's environment and imports it through stdin. If your pipeline uses an older Secure File-based adapter, update its signing step to this template first; adding the variable alone does not change the old adapter. Do not put the secret value or an empty same-named default in YAML. There is no separate secret-authorization step. Configure the secret on each pipeline definition, even when reusing an approved automation key. One key per project or repository gives stronger rotation/revocation isolation.
Migrating from Secure Files? Their resource permissions, approvals, and checks do not transfer to a pipeline-local secret variable. If your signing policy relies on those gates, retain the Secure File-based signing step or adapt the workflow to an appropriately protected secret variable group/template and verify equivalent controls before switching. Creating the variable alone is not a policy-preserving migration.
BOT_GPG_SECRETKEY signs commits/tags; the Build Service token authenticates pushes. BOT_SSH_SECRETKEY is not used on Azure.
Use the project-scoped identity <Your Project> Build Service (<Your Organization>). Under Project settings → Repositories → your repository → Security, grant:
- Read
- Contribute
- Create branch
- Create tag
Grant permissions per repository for least privilege. Each Azure project has its own identity. Do not use the collection-wide Project Collection Build Service Accounts group. If repository access protection prompts for this pipeline's authorization, approve access to this repository.
Identity missing? A project's Build Service identity is created when a pipeline first runs, not necessarily when saved. Configure the secret and queue an initial run to materialize it. That attempt may fail at checkout/push. Once the identity appears, grant the permissions and rerun on master. Before retrying, check whether a bump commit or tag reached the remote; pull/fetch and inspect any partial publication instead of adding another bootstrap commit.
Protect master/develop and, for reviewed modes, stabilization branches. Required-PR policies may need a narrowly approved, branch-scoped automation push exception for generated version commits. Do not give humans blanket bypass or grant Bypass policies when pushing without explicit administrator approval.
After the secret, repository access, and permissions are ready, open your pipeline and choose Run pipeline → master → Run. The earlier push is not retroactive: it occurred before the pipeline existed.
Wait for the entire run, including publication, to succeed. Expected result:
- signed bot commit
bump: version 0.0.1 → 0.1.0; - signed tag
0.1.0.
Pull the bot commit and explicitly fetch tags, then create develop from that stable result:
git checkout master
git pull --ff-only origin master
git fetch origin --tags
git tag -v 0.1.0
git checkout -b develop
git push -u origin developDo not create develop from the original bootstrap commit. If publication fails, inspect the remote and follow recovery; do not create a competing bump or tag.
Permit Squash commit and Merge (no fast-forward) as needed by your selected walkthrough. Prohibit rebase completion. The final commit subject on the target must be the documented PR title, not an unrelated generated merge message.
| Target / action | Final subject |
|---|---|
Ordinary feature/bugfix into develop |
Conventional Commit |
| Open a develop cycle | Start X.Y.Z |
Promote release into master |
Release X.Y.Z |
Promote hotfix into master |
Hotfix X.Y.Z |
Release backmerge into develop |
Backmerge Release X.Y.Z |
Hotfix backmerge into develop |
Backmerge Hotfix X.Y.Z |
For squash, set the final squash subject to the PR title. For merge commits, customize the first line to the PR title. Synchronization and boundary-backmerge steps marked Merge (no fast-forward) must preserve ancestry and untagged bump anchors; do not squash them. Reviewed stabilization PRs follow their mode's merge policy.
In Project settings → Repositories → your repository → Settings, disable inclusion of the PR ID in completion commit messages. This setting arrived in Azure DevOps Services Sprint 270; older Server versions may not expose it. A supported engine recognizes the optional Merged PR 42: prefix for fixed workflow titles such as Start X.Y.Z and Backmerge Release X.Y.Z, but ordinary Conventional Commit increment inference does not reliably normalize it. Ordinary squash PRs must produce a plain final subject, such as feat: add greeting, without the prefix. If your hosting cannot produce that subject, stop and validate an approved alternative before following the ordinary squash steps. The rest of any recognized fixed workflow subject must still match the intended title.
git-tools commit generates and commits by default; use --no-commit to preview. git-tools pr generates text, not a hosted PR: push your source branch and create/complete the PR in Repos → Pull requests yourself.
Azure descriptions are limited to 4,000 UTF-16 code units. Azure origin detection enables the CLI limit automatically; use --azure-limit for custom hosts or --no-azure-limit for other destinations. Oversized output is regenerated once, then retained with a warning if still too long. Inspect and shorten the final text before pasting. See CLI usage and provider configuration/limitations.
- Trust boundary: restrict who can edit the pipeline, its secrets, and credential-bearing YAML/branches. These are mutating push pipelines, not PR validation builds.
pr: nonealone does not protect credentials from untrusted YAML. Use a separate read-only test pipeline for PR validation. - Never log the key. Azure masking does not guarantee protection of individual lines/substrings of a multiline secret. Do not enable shell tracing around secrets, print their environment, or include them in diagnostic artifacts. The examples map the secret only into the import step.
- Agent assumption: use a fresh disposable Microsoft-hosted agent and one automation signing key. Stdin avoids an extra export file, but GPG still stores the imported key in the agent keyring. Reused/self-hosted agents need isolated keyrings, explicit key selection, and cleanup designed separately. These templates do not provide that hardening or a passphrase input.
- History and serialization: retain full history, tags, and remote branch refs. The examples do not serialize concurrent runs; coordinate version-producing pushes and wait/pull/fetch before dependent operations. The generated bump subject skips the next ordinary run, but does not protect against competing pipelines or manual version edits.
- Triggers:
master,develop,release/*,hotfix/*,feature/*, andbugfix/*are included. Reviewed helpersrelease-fix/*andhotfix-fix/*run versioning only when their merge pushes the target branch. - Reviewed flow is a repository-policy choice, not a compliance certification. Read the current engine limitations before enabling writes.
The engine dry-runs an atomic push and falls back to separate pushes only when the server explicitly lacks atomic support. Other failures stop. Inspect remote refs and follow publication and missing-tag recovery. Never force-push a version commit or repeat bootstrap to repair publication; rerunning is not guaranteed to recover a lost local signed tag.
Follow one complete guide: Classic, Classic — Reviewed, Release-led, or Release-led — Reviewed. Each includes its mode policy and edge cases as well as the concrete journey.