Chapter 2 of 6
Architecture at a glance#
The full commit SHA is the release identity. Fixed digests bind the prompt, agent version, model alias, APIM policy, evaluation inputs, and Bicep parameters to it. A changed component creates a new release.
The workflow first proves default-branch lineage and runs the unit, evaluation, adversarial, and observability gates. The same validation job reads the approved framework path and the duplicate-agent review from the control definition, so an unsupported runtime or a rebuilt agent stops the release before Azure. Preview jobs then use environment-scoped OIDC to run Bicep what-if. The apply environments withhold their OIDC values until a reviewer approves the matching preview.
After both deployments pass, API Management moves the approved selector. The release store marks the staged record approved only after routing succeeds. Manual restore reads an approved record, previews the selector change, waits for production approval, and returns traffic to that selected release.
Design choices and tradeoffs#
| Decision | Chosen approach | Benefits | Costs and limitations |
|---|---|---|---|
| Release identity | Full commit SHA plus fixed component digests | Every stage and restore name one release | Any correction requires a new release |
| Access | Separate preview and apply environments with exact OIDC subjects | What-if runs before approval; apply credentials stay withheld | Four trusts and environment protections must stay aligned |
| Agent portfolio | Framework path and duplicate review recorded in the control definition | The release gate stops an unsupported runtime or a rebuilt agent before Azure | Both decisions need a named owner and go stale unless someone updates them |
| Recovery | Manual, production-approved restore from an approved release record | An owner checks the exact release and route before traffic moves | Restore needs an available authority and takes longer than automation |