What to Do When a New Version Is Released

This page is for the engineer who upgrades a customer's configuration repository to a newer version of the code repository. To create a release, see Releasing. For what changed in each version, see the Release history, and for the section overview, Releases and upgrade guidance.

Who does the upgrade depends on the operating model: XMMS engineers in the managed model, the customer's platform team in the self-managed model.

Versioning: how the configuration repository pins the code

You choose the code version in each entry pipeline of the configuration repository.

Azure DevOps: the repository resource mcp-code and its ref:

variables:
  - template: variables.yaml
  - name: mcpRef
    value: release/v4.12

resources:
  repositories:
    - repository: mcp-code
      endpoint: xebia-managed-services-eu.ghe.com
      type: githubenterprise
      name: xmms/xms-cloud-platform-code
      ref: $(mcpRef)

GitHub Actions: the uses: reference and the mcpCodeRef input (keep them identical):

jobs:
  canary:
    uses: xmms/xms-cloud-platform-code/.github/workflows/stage-mcp-hub.yaml@release/v4.12
    with:
      mcpCodeRef: release/v4.12

Pinning release/vX.Y means you get every patch on that branch automatically. Pin a tag (v4.12.2) if the customer needs a fixed version.

Legacy pipelines

To move a tenant from the legacy pipelines to the entry pipelines, see Migrating from an older platform version.

Older customer repositories use a single pipelines/main.yaml (Azure DevOps) or .github/workflows/main.yaml with environment_canary.yml@v… / environment_prod.yml@v…, and run one layer at a time. The steps below still apply; update every ref: and @v… reference in those files, and run the layers one by one in the order foundation, connectivity, (ghrunners), identity, management, firewall, postdeployment. The single-pipeline flow is written out in the Generic update runbook.

Upgrade steps

flowchart LR
    a["1. Current version"] --> b["2. Upgrade guides"] --> c["3. Branch + pre-steps"] --> d["4. Bump the pin"]
    d --> e["5. infrastructure + container"] --> f["6. Canary: plan → apply"] --> g["7. Prod"] --> h["8. Merge + record"]

1. Check the current version

Open the entry pipelines in the configuration repository and record the current mcpRef / ref / @…. All entry files must have the same value; if they differ, find out why before you continue.

2. Read the upgrade guides

Read the version-specific upgrade guide of every version between the current and the target version, oldest first. The guides are cumulative. If a version has no guide, it needs no special steps.

The guides for v4.4.0 up to v4.12.x are in Platform upgrade guides. The guides of the older, separate spoke canvas are in Spoke canvas upgrade guides. To see what each version brought, read the Release history.

Recent examples:

Upgrade	What the guide asks
to v4.11.x (from v4.9.x)	Delete the old DNS policy definitions and initiatives and the BIO initiative from the configuration repository; delete the old DNS policy assignment file; remove the Alerting-LandingZone and XMS-Deploy-DNS-Zones assignments and initiatives in the portal
to v4.12.x (from v4.11.x)	Remove the XMMS-Private-DNS-Zones assignment and initiative in the portal; make sure every App Gateway JSON has a valid firewall_policy_id (lower-case applicationGatewayWebApplicationFirewallPolicies)

3. Create a branch and do the pre-steps

git checkout -b users/<initials>/update-to-v<version>

Do the configuration-repository steps from the guides on this branch. Request PIM elevation if a guide needs portal changes, and do portal clean-up before you continue.

4. Bump the pin

Change every mcpRef / ref / uses: …@ / mcpCodeRef in all entry pipelines (hub, hub-destroy, spoke, spoke-destroy, infrastructure, container) in one commit.

5. Rebuild the tooling

1. If the release changes the job runner Bicep (src/Xebia.Mcp/Files/bicep/), run infrastructure first.
2. Run container, so the mcp image is rebuilt from the new code version.

6. Canary: plan, review, apply

Announce the window to the workload teams first (Maintenance calendar).

Run hub from your branch in Plan (or ApproveModifications) mode and read every layer's plan:

• Expected: the changes listed in the upgrade guides and release notes.
• Stop on unexpected destroys or replacements. If in doubt, ask the XMMS product team before you apply. In the managed model, XMMS engineers do this check. In the self-managed model, the customer's platform team does it, then asks XMMS if it is unsure.

Apply to canary. Then run spoke in Plan mode for one spoke per spoke environment and check that the spokes show no unexpected changes.

Reading the spoke plans

After an upgrade, spoke plans are where surprises show up. Run spoke in Plan mode for every spoke (or at least one per kind of spoke) and write down the result per spoke: no changes, expected changes, or needs a look. Plans on a running platform typically show these expected changes after an upgrade:

Change in the plan	Usually means
The password of a spoke service principal "will be rotated"	The rotation period has passed. The next apply rotates it. If a team already created a new secret by hand, tell them. Federated credentials are not rotated (Change spoke)
Network access of a Key Vault from a subnet "will be removed", or a service endpoint "will be removed" from a subnet	The code no longer creates that access, so something was added by hand or by an older version. Ask the workload team whether it is still needed. If it is, add it in the spoke configuration before you apply
An NSG association "will be created" on a subnet	A subnet that had no NSG gets the baseline NSG. Check that the NSG rules do not cut off traffic that works today
An NSG rule "will be removed"	The rule was not in the code. Confirm with the workload team
Log Analytics daily_quota_gb or retention_in_days changes	The spoke configuration differs from the workspace. Decide which value is right before you apply
Anything that destroys a subscription's association, a Key Vault, a storage account or a virtual network	Stop. Treat as unexpected (Known issues)

Keep the list of spokes and the result per spoke in a table in the work item, and re-run the failed ones after you have resolved them. Do not apply a spoke plan that you have not read.

7. Prod

Repeat step 6 for prod. Make prod-specific changes only where the guide says so.

8. Merge and record

1. Merge the branch to main.
2. Run hub once more from main and check that it plans no changes.
3. Record the new version on the work item, and in the customer overview if you keep one. (The report-version pipeline reports pinned versions to the status API automatically.)

Checklist

• [ ] Current version recorded
• [ ] All upgrade guides between current and target read and done
• [ ] Every entry pipeline pins the same target version
• [ ] infrastructure (if needed) and container run
• [ ] Canary hub planned, reviewed, applied
• [ ] Spokes planned, every plan read, and unexpected changes explained or fixed
• [ ] Prod hub planned, reviewed, applied
• [ ] Merged; a run from main plans no changes