Skip to content

Versions and upgrades

This site documents engine v1.5.0.

Every version number below is the one the platform pins today. When an upgrade lands, update this page first.

Four families of pins carry versions in a customer repository: the engine, the toolchain, the AVM modules, and the ALZ policy libraries. Each one upgrades the same way, through a pull request that plans before it applies.

Engine pins

The engine is consumed as a reusable workflow. Each of the two caller workflows in .github/workflows/ carries the version twice.

File uses: ref engine_ref input
terraform-pr-ops.yml v1.5.0 v1.5.0
drift.yml v1.5.0 v1.5.0

The two pins do different jobs. uses: picks the workflow YAML that GitHub runs. engine_ref picks the engine scripts the workflow checks out at run time. They must hold the same exact tag and move together in the same commit, or new YAML runs old scripts. The resolve job logs the requested engine_ref and the commit it checked out, so a skew is visible at the top of every run.

Exact versions are the contract

vX.Y.Z tags are immutable and callers pin one exactly. There is no moving v1 tag. An earlier policy offered one and it is retired, because it meant a customer could not tell from the file which engine they were running, and a repository could change behaviour with no commit. Nothing arrives automatically, so an upgrade is always a change you can see, review, and revert.

How to upgrade the engine

  1. Read the release notes for the target tag. They call out anything a consumer must change.
  2. Bump both pins in both caller files, in one commit: uses: ...@vX.Y.Z and engine_ref: vX.Y.Z.
  3. Open a pull request.
  4. The plan on that pull request is the smoke test. It exercises resolve, discovery, the plan jobs, and the gates against the new engine.
  5. Get the required reviews, comment /apply if the change needs one, and merge.

Roll back by reverting the pin commit.

See The PR-ops engine for the full caller files.

Toolchain pins

Terraform and Terragrunt are pinned in mise.toml at the repository root. The setup-tools action detects the version manager and installs those versions, so a bump is a one-line change with no workflow edit.

[tools]
terragrunt = "1.0.7"
terraform = "1.15.5"

live/root.hcl also sets floor constraints: Terraform >= 1.12 and Terragrunt >= 1.0. Keep the mise.toml versions at or above those floors.

AVM module versions

Each foundation unit's main.tf sources an Azure Verified Module with an explicit version argument.

Module Version Unit
Azure/avm-ptn-alz-management/azurerm 0.9.0 management-resources
Azure/avm-ptn-alz/azurerm 0.21.0 landing-zones
Azure/avm-ptn-monitoring-amba-alz/azurerm 0.4.0 amba
Azure/avm-ptn-alz/azurerm 0.21.0 amba

To upgrade, change the version argument, open a pull request, and review the plan. The Azure/avm-ptn-alz/azurerm version appears in two units. Keep both on the same version so the two ALZ pattern deployments agree.

Provider constraints live alongside them: hashicorp/azurerm at ~> 4.0, Azure/azapi at ~> 2.4, and Azure/alz at ~> 0.21. A major AVM bump usually moves the alz provider constraint too. See The foundation units.

ALZ and AMBA library refs

Two units set library_references on the alz provider.

Library Ref Set in
platform/alz 2026.04.2 landing-zones, amba
platform/amba 2026.06.2 amba

Keep the platform/alz ref identical in both units. The vendored NRIT library is the third entry, a custom_url with no ref. It lives in the repository, so you edit it in place rather than bumping it.

Re-sync the vendored architecture on every platform/alz bump

live/_foundation/landing-zones/lib/architecture_definitions/nrit.alz_architecture_definition.json is a full copy of the stock alz architecture plus one line: the nrit_tags archetype on the intermediate root. The module needs a complete architecture, so the whole hierarchy is duplicated there.

When you bump the platform/alz ref, fetch the stock architecture at the new version, diff it against that file, apply any hierarchy changes upstream made, and keep nrit_tags on the root. Nothing tracks this. No test fails and no plan warns if the hierarchy has moved on. Put the re-sync in the same pull request as the ref bump.

See The vendored policy library.

What bumps the engine major

The caller contract is what a consumer repository has to provide. A breaking change to any of it bumps the major version:

  • workflow inputs,
  • secrets the workflow expects,
  • hook conventions, including the meaning of $TFPR_ENGINE_DIR and the step seams,
  • required caller-side repository variables,
  • required GitHub environments.

Everything else is a minor or a patch. See projects.yml schema and Hook and step model for the surfaces this covers.

Checking for updates

Engine releases live on the GitHub releases page of nrit-tf-pr-ops. There is no changelog file in the repository, so the release notes on the tag are the record of what changed and what a consumer must do about it.

AVM module versions come from the Terraform registry. The ALZ and AMBA library refs come from the upstream Azure Landing Zones library releases.

Upgrade one thing at a time

Bump one module, one library, or the engine per pull request. The plan diff stays readable, and a revert is one commit. Upgrading everything at once turns a readable diff into a wall of noise.

The process is the same in each case:

  1. Change the version, ref, or the caller pins on a branch.
  2. Open a pull request. The engine plans the impacted units and posts the diff.
  3. Review the plan and the gate output.
  4. Comment /apply after approval.
  5. Roll back by reverting the change and applying again.

See Plan and apply.