Golden path templates: design upgrades after code generation

Operational decision

A Java billing worker was created from template version 4.2; version 5.0 switches to a new workload identity and changes the CI workflow permissions. Record the template ID and original version in the service catalog. An upgrade tool reads the repository, proposes a patch, and checks whether affected files still match the known generated baseline. It opens a reviewable change for the service owner, runs build and deployment checks, and marks the adoption only after a real production rollout uses the new identity. If the owner customized the workflow, produce a conflict with a precise diff rather than replacing it. Test three consumers: untouched generated code, a locally modified workflow, and an old service that skipped version 4.5. Define whether the migration supports each starting version or requires intermediate steps. Keep a cutoff date for the old identity and track services still using it. A new repository created from version 5.0 is not evidence that the existing fleet has upgraded.

Template migration contract
Template: java-billing-worker
From: 4.2 (or supported intermediate)
To: 5.0
Managed files: declared and baseline-checked
Conflict: owner review required
Conformance: CI permission and identity tests
Adoption proof: deployed service uses new identity

Cost and verification

Scanning R repositories and M managed files is O(R × M) metadata comparisons, plus each repository's tests. Forced blanket changes are faster until they overwrite local behavior; reviewable migrations cost engineering time but reduce outage risk. Measure template version distribution, migration conflict rate, time to adopted production state, and policy violations remaining after cutoff. A catalog version field should reflect observed adoption, not merely that a patch was proposed.

Common Mistakes

• Do not assume template updates modify repositories already generated.
• Do not overwrite a team-customized workflow without a reviewed diff.
• Do not mark an upgrade adopted before the service passes its deployment gate.

Connected lessons

• DevOps: delivery, infrastructure, and reliable operations
• CI matrix gates: distinguish skipped, canceled, experimental, and passed
• Terraform modules: small interfaces and explicit state owners
• Release evidence: tie one deployed digest to one approval decision
• Policy exceptions: make a temporary bypass expire and prove its scope

Practice and check

• Project: prove a self-service platform request end to end
• DevOps platform self-service decisions