Code Traceability¶
Scope
Traceability notes and evidence paths for connecting AzAWSLab claims to implementation source, workflow execution, Terraform roots, and public-safe evidence. This page focuses on repository traceability that can be reviewed from public source and evidence paths.
Traceability model¶
AzAWSLab uses two complementary traceability routes.
The first route connects a portfolio claim to implementation source and evidence. This is the reviewer-facing route: a claim leads to a repository path, and that path leads to public-safe evidence.
The second route follows an infrastructure change through the delivery pipeline. This is the delivery engineering route: a Git change flows through GitHub Actions, Terraform plan, review, controlled apply, and validation evidence.
Portfolio claim
|
v
Documentation or engineering note
|
v
Implementation source
|
v
Evidence folder
|
v
Reviewer verification
Git commit
|
v
GitHub Actions workflow run
|
v
OIDC-authenticated Terraform plan
|
v
Review or approval gate
|
v
Controlled Terraform apply
|
v
Validation output and evidence folder
This gives reviewers two practical routes through the same platform: business capability to evidence, or delivery pipeline to validation output.
Capability-to-source map¶
Delivery traceability chain¶
The Release 2 state and pipeline map documents the delivery path from Git to Azure through GitHub Actions, OIDC-authenticated Terraform plan, review, controlled apply, and validation evidence.
| Stage | What it proves | Where to inspect |
|---|---|---|
| Git commit | The change starts from version-controlled source. | Git history and pull request context |
| GitHub Actions workflow | The change enters a controlled workflow rather than an operator-local apply path. | .github/workflows/ |
| OIDC-authenticated Terraform plan | The workflow authenticates with OIDC and generates reviewable Terraform plan output without long-lived Azure deployment secrets. | Release 2 Terraform CI workflow |
| Review or approval gate | The plan is reviewed before infrastructure mutation. | Terraform state and pipeline map |
| Controlled apply | Apply is bounded to the selected root and profile-aware workflow path. | Release 2 workflow folder |
| Evidence folder | Validation output is preserved for public-safe review. | docs/release2/evidence/ |
Reviewer workflow¶
A technical reviewer can validate a claim by following the source and evidence route.
Use this sequence:
- Start from a claim on the portfolio page.
- Open the related engineering note or release document.
- Follow the source path to Terraform, Ansible, Kubernetes, workflow, or script code.
- Open the evidence folder linked from the note.
- Confirm the evidence shows the expected implementation signal.
- Check the Release 2 state map when the claim involves Terraform root ownership, OIDC, controlled apply, or active profile guardrails.
Code Traceability is separate from GitHub Actions OIDC for a specific reason. OIDC explains how delivery authenticates. Code Traceability explains how reviewers move from claim, to source, to evidence.
Enterprise traceability hardening pattern¶
The current public portfolio provides claim-to-source-to-evidence traceability. In stricter enterprise environments, the same pattern can be extended further:
| Hardening pattern | Purpose |
|---|---|
| Required resource tags | Enforce source, owner, environment, Terraform root, and deployment context on resources. |
| Activity Log export | Preserve cloud control-plane operations in a central logging workspace or immutable storage target. |
| Protected environments | Require reviewer approval before workflow apply jobs can run. |
| Signed plan or provenance records | Attach a signed artifact linking commit, workflow run, plan, and apply output. |
| Azure Policy tag enforcement | Prevent resource creation when required traceability tags are absent. |
| Evidence retention policy | Keep validation output, sanitized logs, and screenshots according to review or audit needs. |
These controls extend the current evidence structure. They add a formal audit-retention layer for organizations that require it.
Engineering significance¶
Code Traceability shows four delivery engineering decisions:
- Portfolio claims are connected to implementation source and evidence, not left as narrative statements.
- Release 2 delivery is traceable from Git through GitHub Actions, Terraform plan, approval, controlled apply, and validation evidence.
- Reviewers can inspect public-safe evidence without needing privileged access to the live tenant.
- Enterprise traceability patterns can be layered on top through resource tags, Activity Log export, policy enforcement, and provenance records.
This page is the reviewer bridge between architecture context and implementation evidence.
Evidence map¶
| Claim | Repository location | What to verify |
|---|---|---|
| Portfolio claims connect to source and evidence | CODE_TRACEABILITY.md | Claim-to-documentation-to-source-to-evidence mapping |
| Release 2 delivery path is documented | Terraform state and pipeline map | Git commit, workflow, plan, review, apply, and evidence flow |
| OIDC workflow implementation is inspectable | Release 2 Terraform CI workflow | id-token: write, azure/login@v2, and Terraform validation stages |
| Release 2 evidence is organized by capability | Release 2 evidence folder | Evidence folders for Terraform, networking, AWX, AKS, AVD, AWS branch, and O6 |
| This page provides reviewer traceability | This page | Capability map, delivery chain, reviewer workflow, and hardening pattern |
Review takeaway¶
Code Traceability shows that AzAWSLab is documented, sourced, and reviewable.
A reviewer can start with a portfolio claim, follow it to source implementation, inspect the evidence folder, and understand how the delivery pipeline connects code changes to platform validation.