---

name: configure-env-variables description: >- Configures environment variables for Power Pages site settings to support ALM across environments. Creates environment variable definitions in Dataverse, guides the user through linking site settings to those variables via the Power Pages Management app, adds the variables to the solution, and generates a deployment-settings.json file with per-stage override values. Use when asked to: "configure environment variables", "add env vars", "set up deployment variables", "make site settings environment-specific", "configure ALM variables", "set up env-specific settings", "add deployment settings", "configure per-environment settings". user-invocable: true argument-hint: "Optional: site setting name or env var schema name to pre-select" allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion model: opus

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

configure-env-variables

Creates and links Dataverse environment variables to Power Pages site settings, enabling different configuration values per deployment environment (dev vs staging vs prod). Generates deployment-settings.json for use by deploy-pipeline.

Background

Power Pages site settings can be backed by environment variables (GA March 2025, enhanced data model only). When linked:

• The site setting's mspp_source changes from 0 (static) to 1 (environment variable)
• The runtime reads the env var value for the current environment instead of the static mspp_value
• During pipeline deployment, target-environment values are injected via deploymentsettingsjson

API note: The site setting → env var link is set via a HAR-confirmed OData PATCH pattern (v9.0, EnvironmentValue nav property, if-match: * and clienthost: Browser headers required). This is handled by scripts/lib/link-site-setting-to-env-var.js. All steps are fully automated.

Prerequisites

• PAC CLI authenticated: pac auth who
• Azure CLI token available: az account get-access-token
• .solution-manifest.json exists in the project root (run setup-solution first)
• Power Pages site deployed to dev environment (.powerpages-site/ folder exists)

Phase 0 — ALM plan gate

plan-alm is the front door. When the user expresses an ALM intent (promote / ship / deploy / set up CI-CD / move to staging / push to prod), the orchestrator (/power-pages:plan-alm) should run first. This Phase 0 enforces that and is meant to fail closed when there's no plan, not to be a one-time check the user can dismiss forever.

Skip rule. If this skill was invoked as part of an active plan-alm orchestration, skip Phase 0 entirely and proceed to Phase 1. The gate helper exposes this via its inExecution block — pass through silently to Phase 1 when:

inExecution.status === "active"

The helper computes this from docs/.alm-plan-data.json — PLAN_STATUS === "In Execution" AND LAST_INVOCATION_AT within the last 60 minutes. check-alm-plan.js refreshes LAST_INVOCATION_AT automatically on every invocation that finds the plan in execution, so each in-chain skill keeps the chain alive for the next one — even multi-hour deploys (deploy-pipeline alone can take 60 min per stage) survive the window without the chain incorrectly de-classifying. Stalled chains (no heartbeat for > 60 min) reclassify as stale-heartbeat and Phase 0 gates fire normally so an abandoned plan doesn't silently bypass user confirmation.

When inExecution.status is anything other than "active" ("not-running", "stale-heartbeat", "no-plan"), run the Phase 0 gate flow below. Branch on the remaining helper fields:

Step 1 — Run the gate helper.

node "${PLUGIN_ROOT}/scripts/lib/check-alm-plan.js" --projectRoot "."

The helper returns JSON with { exists, deferred, stale, staleness: { reason, detail }, generatedAt, planStatus, ... }. Pass --envUrl, --token, --solutionId once Phase 1 has acquired them if you also want a freshness check; otherwise the helper does an existence-only check, which is sufficient for the gate decision below.

Step 2 — Branch on the result.

| Result | Behavior | |---|---| | deferred: true | The user has explicitly deferred ALM for this project (.alm-deferred marker present). Pass through silently to Phase 1 — do not nag. | | exists: false | The user hasn't run plan-alm yet. See Step 3. | | exists: true, stale: false | Plan is current. Pass through silently to Phase 1. | | exists: true, stale: true (reason: solution-modified) | The solution changed after the plan was generated. See Step 4. |

Step 3 — No plan. Tell the user:

"No ALM plan exists for this project. /power-pages:plan-alm builds one — it detects the project state, asks about your promotion strategy (PP Pipelines vs Manual export/import), classifies which site settings should become environment variables, and orchestrates the right skills (including this one) in the right order. Want me to run plan-alm now?"

<!-- gate: configure-env-variables:0.no-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · configure-env-variables:0.no-plan): Fail-closed entry gate when check-alm-plan.js returns exists:false. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Run /power-pages:plan-alm first? | ALM plan gate | Yes — run /power-pages:plan-alm now (Recommended), Continue without a plan (advanced — I know what I'm doing), Cancel |

• Yes (Recommended) → invoke /power-pages:plan-alm. It builds the plan and returns — plan-alm is a planner and does not deploy. This skill then re-runs the Phase 0 check (now exists:true) and proceeds to Phase 1, picking up the pre-classified siteSettings from docs/alm/alm-plan-context.json.
• Continue without a plan → set BYPASSED_PLAN_GATE = true and proceed to Phase 1.
• Cancel → exit cleanly.

Step 4 — Stale plan. Tell the user:

"ALM plan exists from {generatedAt} but the source solution has been modified since (at {solution.modifiedon}). Components may have changed. Re-running plan-alm will refresh the analysis and the rendered HTML."

<!-- gate: configure-env-variables:0.stale-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · configure-env-variables:0.stale-plan): Fail-closed entry gate when check-alm-plan.js returns stale:true (solution-modified-since-plan). Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Refresh the plan first? | ALM plan freshness | Refresh — re-run /power-pages:plan-alm (Recommended), Continue with the existing plan, Cancel |

• Refresh (Recommended) → invoke /power-pages:plan-alm. After completion, re-run the Phase 0 helper once to confirm freshness; if still stale, surface the detail and proceed to Phase 1 anyway (don't infinite-loop).
• Continue → set STALE_PLAN_ACK = true and proceed to Phase 1.
• Cancel → exit cleanly.

Why this gate exists. Direct invocation of configure-env-variables creates env var definitions and a deployment-settings.json without the orchestrator's per-stage value gathering, site-setting classification (keepAsIs / promoteToEnvVar / authNoValue / excluded), and pipeline-strategy alignment. Users running this skill standalone often pick env var schema names that don't align with the plan's solution split, miss authNoValue settings that the plan classified for inclusion, or generate stage names that don't match the pipeline configured later by setup-pipeline. The gate ensures plan-alm either ran (so env var decisions are coherent with the rest of the deployment plan) or the user explicitly chose to bypass it.

Phase 1 — Discover Existing State

Read project context and query Dataverse to understand what's already configured.

1.1 Read project files:

cat .solution-manifest.json          # get solutionUniqueName, environmentUrl, publisher.prefix
cat docs/alm/last-pipeline.json              # get hostEnvUrl, stages[].name
ls .powerpages-site/site-settings/   # list all site setting YAML files

1.2 Acquire token and verify prerequisites:

node "${PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js" \
  --envUrl "{devEnvUrl}" \
  --require-manifest

Capture output as JSON; extract .envUrl (store as devEnvUrl) and .token (store as TOKEN).

1.3 Query existing env vars in the environment:

GET {devEnvUrl}/api/data/v9.2/environmentvariabledefinitions?$select=schemaname,displayname,type,defaultvalue,environmentvariabledefinitionid&$orderby=schemaname

1.4 Query site settings that already have env vars linked (mspp_source = 1):

GET {devEnvUrl}/api/data/v9.2/mspp_sitesettings?$filter=mspp_source eq 1 and _mspp_websiteid_value eq {WEBSITE_ID}&$select=mspp_name,mspp_source,_mspp_environmentvariable_value,mspp_envvar_schema

Get WEBSITE_ID from .powerpages-site/website.yml → id field.

1.5 Parse site setting YAML files to list all settings and their current source:

• Files with source: 1 are already env-var-backed
• Files with source: 0 or no source field are static

Present a summary table to the user:

Current site settings (static):   48
Already env-var-backed:             3
Existing env var definitions:       2

Phase 2 — Select Site Settings and Plan Env Vars

Ask the user which site settings should be backed by environment variables. Present the list of static site settings as candidates. Recommend settings that are likely to vary per environment:

Common candidates:

• Authentication/OpenIdConnect/AzureAD/ClientId — Entra ID app registration differs per env
• Authentication/OpenAuth/Microsoft/ClientId — OAuth app ID
• Authentication/OpenAuth/Microsoft/ClientSecret — OAuth secret (use Secret type)
• Authentication/Registration/LocalLoginEnabled — may differ in dev vs prod
• Any Authentication/Registration/OpenRegistrationEnabled — open sign-up policy
• Custom site settings the user has added

<!-- gate: configure-env-variables:2.selection | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · configure-env-variables:2.selection): User picks which site settings get promoted to env vars. Multi-select. Cancel exits before any env var definitions are created.

Ask via AskUserQuestion:

"Which site settings should be backed by environment variables? I'll create an env var for each and guide you through linking them.

Here are the candidates (enter numbers, comma-separated):

1. Authentication/Registration/LocalLoginEnabled (currently: true)
2. Authentication/OpenIdConnect/AzureAD/ClientId (currently: empty)
3. [other settings...] N. I'll type my own setting names"

For each selected setting, ask for:

1. Env var schema name — generate via ${PLUGIN_ROOT}/scripts/lib/generate-env-var-schema-name.js (single source of truth shared with setup-solution):

   node "${PLUGIN_ROOT}/scripts/lib/generate-env-var-schema-name.js" \
     --publisherPrefix "{publisherPrefix}" --settingName "{settingName}"
   

   Output: { schemaName, sanitized }. The canonical rule is {prefix}_{settingName.replace(/[^A-Za-z0-9]+/g,'_').toLowerCase()} — e.g. Authentication/Registration/LocalLoginEnabled becomes ids_authentication_registration_localloginenabled. Do NOT inline a custom rule here: setup-solution emits schema names from this helper, and configure-env-variables MUST match what setup-solution already created (otherwise the link to the existing site setting fails). The user can override the suggestion if they have a reason, but the default must come from the helper.
2. Display name (human-readable)
3. Type: String (default), Boolean, Number, Secret
4. Dev/source value (default = current mspp_value from YA