Skill

sdaf-plan-and-test-semantics

Name: sdaf-plan-and-test-semantics
Author: Azure (Microsoft)

manage SDAF plan and test semantics

Published by Azure (Microsoft) Updated Sep 2

Covers Azure GitHub Actions Automation Azure DevOps CI/CD

Description

Explain SDAF plan-only / test / apply semantics without pretending they are universal. Compares the documented Local commands, Azure DevOps wrapper pipelines, and GitHub Actions workflows for control plane, workload zone, and SAP system: local stage commands show Terraform plans and then apply after approval; ADO/GitHub workload-zone and SAP-system test runs stop after the plan; the current hosted control-plane test options do not provide a plan-only run. Use when a user says "what does test do in SDAF", "is this a real dry run", "plan-only vs apply", "workflow 01 dry-run", "pipeline 02 test", or "TEST_ONLY". Do NOT use to actually deploy a stage or to triage a failed run (see sdaf-control-plane-bootstrap / sdaf-workload-zone / sdaf-sap-system / sdaf-failure-triage).

SKILL.md

SDAF Plan and Test Semantics

Context-primer. Answers "what does test / plan-only / apply mean here?" across surfaces. Canonical rule: there is no SDAF-wide dry-run switch. Classify by execution surface and deployment stage before answering.

For the file-by-file evidence matrix, including the hosted wrapper docs and workflow/pipeline paths, see references/plan-test-matrix.md.

When to invoke

Trigger on: "what does test do", "is this a dry run", "plan-only vs apply", "control-plane dry-run limitation", "workflow 01 dry-run", "pipeline 02 test", "TEST_ONLY", "which SDAF stages can review a Terraform plan without applying".

Do NOT trigger on: actually deploying a control plane / workload zone / SAP system, or triaging a failed run after the fact.

Rule zero — identify the surface and stage first

docs/deployment-options.md is explicit that Local, Azure DevOps, and GitHub Actions are different execution models. Never answer "test means X in SDAF" without naming:

the surface (Local / ADO / GitHub); and
the stage (control plane / workload zone / SAP system).

The shortest correct answer

Path	What plan/test means	What apply means
Local control plane	No separate documented `test` switch. `deploy_controlplane.sh` displays Terraform plans and asks for approval before apply.	The same run applies after operator approval.
Local workload zone	No separate documented local `test` path. `install_workloadzone.sh` shows the plan and waits for approval.	The same run applies after approval.
Local SAP system	No separate documented local `test` path. `installer.sh` shows the plan and waits for approval.	The same run applies after approval.
ADO control plane (`01`)	`test` exists on the wrapper/template, but current docs say it is not forwarded to the control-plane scripts. Treat it as not plan-only.	The queued run is state-changing.
ADO workload zone (`02`)	`test: true` becomes `TEST_ONLY` and the hosted installer exits after Terraform plan.	Re-queue the same pipeline with `test: false`.
ADO SAP system (`03`)	`test: true` becomes `TEST_ONLY` and the hosted installer exits after Terraform plan.	Re-queue the same pipeline with `test: false`.
GitHub control plane (`01`)	The workflow exposes a dry-run input, but the docs say it does not reach either control-plane script.	Treat the run as state-changing; get a reviewed control-plane plan through a separately validated SDAF path first.
GitHub workload zone (`03`)	Enable the test option, review the plan, then rerun with test disabled. The workflow exports `TEST_ONLY`.	Re-dispatch workflow `03` with test disabled.
GitHub SAP system (`05`)	Enable the test option, review the plan, then rerun with test disabled. The workflow exports `TEST_ONLY`.	Re-dispatch workflow `05` with test disabled.

Local / scripted semantics

For local execution, the docs do not define a universal test flag that operators should export by hand. Instead, the documented stage commands themselves are the review gate:

docs/local/03-00-control-plane.md § Run: deploy_controlplane.sh displays Terraform plans and asks for approval before apply.
docs/local/04-00-workload-zone.md § Run: install_workloadzone.sh displays the plan and asks for approval before apply.
docs/local/05-00-sap-system.md § Run: installer.sh displays the plan and asks for approval before apply.

If the operator is on Local, answer with the documented stage command, not with a hosted-only TEST_ONLY story.

Hosted semantics

This is the boundary that prevents most bad advice:

For Azure DevOps or GitHub Actions, answer from the documented pipeline or workflow inputs and outcomes. Do not transfer Local behavior to hosted automation merely because both surfaces use the word test.

Control-plane special case

The control plane is different from workload zone and SAP system:

Local control-plane docs rely on interactive plan review inside the documented run.
Current ADO and GitHub control-plane wrappers expose a test/dry-run input, but the reviewed docs say that input is not forwarded to the control-plane scripts.

So the correct answer to "is control-plane test safe?" is no for the hosted wrappers as currently documented.

Hard rules

Do not claim there is a single SDAF-wide dry-run flag.
Do not transfer Local behavior to hosted automation or vice versa.
Do not tell an operator to rely on ADO/GitHub control-plane test as a safety gate.
For local operator-reviewed deployment, do not add --auto-approve (docs/local/03-00-control-plane.md § Review before execution; docs/local/04-00-workload-zone.md § Review before execution; docs/local/05-00-sap-system.md § Review before execution).

Hand-off

Actual control-plane execution → sdaf-control-plane-bootstrap
Actual workload-zone execution → sdaf-workload-zone
Actual SAP-system execution → sdaf-sap-system
Failed / contradictory run outcomes → sdaf-failure-triage

More skills from the sap-automation repository

View all 18 skills

SkillTagsUpdated

More from Azure (Microsoft)

View publisher

SkillTagsUpdated