Implement two-phase Bicep deployment for Container Apps + ACR to eliminate circular dependency

[Copilot]

The existing container app Bicep patterns caused a circular dependency when scoping the AcrPull role assignment to a module, and offered conflicting alternatives (admin credentials, registries:[{identity:'system'}]) that were either insecure or structurally problematic.

Changes

azure-prepare/references/services/container-apps/bicep.md

• Replaced all prior registry auth patterns with a single canonical two-phase module approach
• Phase 1: Container App with public placeholder image + system-assigned MI, no registries block — AZD updates the real image via Azure API post-provision
• Phase 2: acr-pull-role.bicep as a separate module consuming Phase 1 outputs — neither ACR nor Container App depends on it, breaking the cycle
• Added main.bicep wiring example connecting both phases

// Phase 1 — no registries block, placeholder boots cleanly
module api './modules/container-app.bicep' = {
  params: { containerImageName: 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest' }
}

// Phase 2 — role assignment depends on Phase 1 outputs only
module acrPullRole './modules/acr-pull-role.bicep' = {
  params: {
    acrName: containerRegistry.outputs.name
    principalId: api.outputs.systemAssignedMIPrincipalId
  }
}

azure-deploy/references/pre-deploy-checklist.md

• Updated "Container Apps + ACR — Pre-Deploy RBAC Health Check" to note that azd provision now always succeeds (placeholder image; no ACR pull during provision); RBAC propagation check before azd deploy remains mandatory

azure-deploy/references/recipes/azd/errors.md

• Updated "Container App Revision Timeout" cause description to reference the two-phase pattern

Version bumps

• azure-prepare: 1.1.8 → 1.1.9
• azure-deploy: 1.0.15 → 1.0.16

[github-actions]

Details

# 🔍 Token Analysis Report

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts compare --base origin/main --head HEAD --markdown

📊 Token Change Report

Comparing origin/main → HEAD

Summary

Metric	Value
📈 Total Change	+335 tokens (+3%)
Before	11,124 tokens
After	11,459 tokens
Files Changed	3

Changed Files

File	Before	After	Change
plugin/skills/azure-prepare/references/services/container-apps/bicep.md	1,081	1,250	+169 (+16%)
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	2,204	2,347	+143 (+6%)
plugin/skills/azure-deploy/references/recipes/azd/errors.md	3,429	3,452	+23 (+1%)

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts check --markdown

📊 Token Limit Check Report

Checked: 543 files
Exceeded: 74 files

⚠️ Files Exceeding Token Limits

File	Tokens	Limit	Over By
.github/skills/analyze-test-run/SKILL.md	2471	500	+1971
.github/skills/file-test-bug/SKILL.md	628	500	+128
.github/skills/sensei/README.md	3531	2000	+1531
.github/skills/sensei/SKILL.md	3026	500	+2526
.github/skills/sensei/references/EXAMPLES.md	3701	2000	+1701
.github/skills/sensei/references/LOOP.md	4181	2000	+2181
.github/skills/sensei/references/SCORING.md	4200	2000	+2200
.github/skills/skill-authoring/SKILL.md	839	500	+339
plugin/skills/appinsights-instrumentation/SKILL.md	908	500	+408
plugin/skills/azure-ai/SKILL.md	817	500	+317
plugin/skills/azure-aigateway/SKILL.md	1258	500	+758
plugin/skills/azure-aigateway/references/policies.md	2342	2000	+342
plugin/skills/azure-cloud-migrate/references/services/functions/lambda-to-functions.md	2600	2000	+600
plugin/skills/azure-cloud-migrate/references/services/functions/runtimes/javascript.md	2181	2000	+181
plugin/skills/azure-compliance/SKILL.md	1185	500	+685
plugin/skills/azure-compute/SKILL.md	755	500	+255
plugin/skills/azure-compute/workflows/vm-recommender/vm-recommender.md	2393	2000	+393
plugin/skills/azure-cost/SKILL.md	1861	500	+1361
plugin/skills/azure-deploy/SKILL.md	1643	500	+1143
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	2347	2000	+347
plugin/skills/azure-deploy/references/recipes/azd/errors.md	3452	2000	+1452
plugin/skills/azure-deploy/references/troubleshooting.md	2038	2000	+38
plugin/skills/azure-diagnostics/SKILL.md	1132	500	+632
plugin/skills/azure-diagnostics/aks-troubleshooting/networking.md	2147	2000	+147
plugin/skills/azure-diagnostics/aks-troubleshooting/node-issues.md	2003	2000	+3
plugin/skills/azure-enterprise-infra-planner/SKILL.md	991	500	+491
plugin/skills/azure-enterprise-infra-planner/references/constraints/compute-apps.md	2022	2000	+22
plugin/skills/azure-hosted-copilot-sdk/SKILL.md	1260	500	+760
plugin/skills/azure-kubernetes/SKILL.md	2266	500	+1766
plugin/skills/azure-kusto/SKILL.md	2149	500	+1649
plugin/skills/azure-messaging/SKILL.md	967	500	+467
plugin/skills/azure-prepare/SKILL.md	2767	500	+2267
plugin/skills/azure-prepare/references/aspire.md	4003	2000	+2003
plugin/skills/azure-prepare/references/plan-template.md	2559	2000	+559
plugin/skills/azure-prepare/references/recipes/azd/aspire.md	3069	2000	+1069
plugin/skills/azure-prepare/references/recipes/azd/terraform.md	3012	2000	+1012
plugin/skills/azure-prepare/references/research.md	2217	2000	+217
plugin/skills/azure-prepare/references/resources-limits-quotas.md	3322	2000	+1322
plugin/skills/azure-prepare/references/security.md	2133	2000	+133
plugin/skills/azure-prepare/references/services/functions/bicep.md	3065	2000	+1065
plugin/skills/azure-prepare/references/services/functions/templates/SPEC-composable-templates.md	6187	2000	+4187
plugin/skills/azure-prepare/references/services/functions/templates/recipes/composition.md	4649	2000	+2649
plugin/skills/azure-prepare/references/services/functions/terraform.md	3358	2000	+1358
plugin/skills/azure-quotas/SKILL.md	3445	500	+2945
plugin/skills/azure-quotas/references/commands.md	2644	2000	+644
plugin/skills/azure-resource-lookup/SKILL.md	1288	500	+788
plugin/skills/azure-resource-visualizer/SKILL.md	2054	500	+1554
plugin/skills/azure-storage/SKILL.md	1180	500	+680
plugin/skills/azure-upgrade/SKILL.md	1001	500	+501
plugin/skills/azure-upgrade/references/services/functions/automation.md	3463	2000	+1463
plugin/skills/azure-upgrade/references/services/functions/consumption-to-flex.md	2773	2000	+773
plugin/skills/azure-validate/SKILL.md	906	500	+406
plugin/skills/entra-app-registration/SKILL.md	2067	500	+1567
plugin/skills/entra-app-registration/references/api-permissions.md	2545	2000	+545
plugin/skills/entra-app-registration/references/cli-commands.md	2211	2000	+211
plugin/skills/entra-app-registration/references/console-app-example.md	2752	2000	+752
plugin/skills/entra-app-registration/references/oauth-flows.md	2375	2000	+375
plugin/skills/microsoft-foundry/SKILL.md	2870	500	+2370
plugin/skills/microsoft-foundry/foundry-agent/create/create.md	3016	2000	+1016
plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md	5555	2000	+3555
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/eval-datasets.md	2342	2000	+342
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/trace-to-dataset.md	4268	2000	+2268
plugin/skills/microsoft-foundry/foundry-agent/observe/observe.md	2547	2000	+547
plugin/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md	2701	2000	+701
plugin/skills/microsoft-foundry/foundry-agent/troubleshoot/troubleshoot.md	2164	2000	+164
plugin/skills/microsoft-foundry/models/deploy-model/SKILL.md	1640	500	+1140
plugin/skills/microsoft-foundry/models/deploy-model/capacity/SKILL.md	1739	500	+1239
plugin/skills/microsoft-foundry/models/deploy-model/customize/SKILL.md	2235	500	+1735
plugin/skills/microsoft-foundry/models/deploy-model/customize/references/customize-workflow.md	3335	2000	+1335
plugin/skills/microsoft-foundry/models/deploy-model/preset/SKILL.md	1226	500	+726
plugin/skills/microsoft-foundry/models/deploy-model/preset/references/preset-workflow.md	5534	2000	+3534
plugin/skills/microsoft-foundry/quota/quota.md	2288	2000	+288
plugin/skills/microsoft-foundry/quota/references/capacity-planning.md	2080	2000	+80
plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md	2162	2000	+162

Consider moving content to references/ subdirectories.

---

Automated token analysis. See skill authoring guidelines for best practices.

[Copilot]

Pull request overview

Updates the Container Apps + ACR guidance to a canonical “two-phase” (module-decoupled) Bicep pattern intended to avoid circular dependencies around AcrPull role assignments, and aligns azure-deploy troubleshooting/checklists with that guidance.

Changes:

• Bumped skill versions for azure-prepare and azure-deploy.
• Rewrote Container Apps Bicep reference to a two-phase/module approach (placeholder image + MI first; AcrPull role assignment module second) and added a main.bicep wiring example.
• Updated deploy checklist + azd error guidance to reference the new pattern and its RBAC propagation implications.

Show a summary per file

File	Description
plugin/skills/azure-prepare/SKILL.md	Version bump to reflect updated references.
plugin/skills/azure-prepare/references/services/container-apps/bicep.md	Replaced registry auth patterns with two-phase/module guidance and new wiring examples.
plugin/skills/azure-deploy/SKILL.md	Version bump to reflect updated references.
plugin/skills/azure-deploy/references/recipes/azd/errors.md	Updated revision-timeout cause narrative to reference the new pattern.
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	Updated RBAC health-check section to incorporate the two-phase guidance.

Copilot's findings

Comments suppressed due to low confidence (2)

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:22

• The Phase 1 Bicep snippet isn’t self-contained: it references identifiers like appName, location, containerAppsEnvironment, and serviceName that are not defined in the snippet. For copy/paste usability, either declare these as params in the snippet or replace them with clear placeholders (e.g., <app-name>, <location>) and add a short note explaining where they come from.

resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  name: appName
  location: location
  identity: {
    type: 'SystemAssigned'

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:90

• In the main.bicep wiring example, scope: rg is used but rg is not defined anywhere in this doc. To keep the example valid, either define rg (e.g., an existing resourceGroup resource) or use scope: resourceGroup() / omit scope if the deployment is already at RG scope.

module containerRegistry './modules/container-registry.bicep' = {
  name: 'containerRegistry'
  scope: rg
  params: { /* ... */ }
}

• Files reviewed: 5/5 changed files
• Comments generated: 3

[Copilot]

Pull request overview

Updates the skill documentation to standardize a two-phase Bicep deployment pattern for Azure Container Apps + ACR, intended to avoid circular dependencies around AcrPull role assignments, and aligns deployment troubleshooting/checklists with that pattern.

Changes:

• Replaced prior Container Apps + ACR registry-auth patterns with a documented two-phase module approach (placeholder image + separate AcrPull module).
• Updated azd deployment guidance (pre-deploy RBAC health check + revision timeout troubleshooting) to reference the two-phase pattern.
• Bumped skill metadata versions for azure-prepare and azure-deploy.

Show a summary per file

File	Description
plugin/skills/azure-prepare/SKILL.md	Version bump to reflect updated guidance set.
plugin/skills/azure-prepare/references/services/container-apps/bicep.md	Documents the new two-phase Container Apps + ACR Bicep approach and wiring example.
plugin/skills/azure-deploy/SKILL.md	Version bump to reflect updated guidance set.
plugin/skills/azure-deploy/references/recipes/azd/errors.md	Updates revision-timeout troubleshooting to reference the two-phase pattern.
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	Updates RBAC health check guidance to reference the two-phase pattern.

Copilot's findings

Comments suppressed due to low confidence (3)

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:16

• This inline comment (“No registries block needed”) is likely to be read as “no registry configuration is needed at all”. Even if you omit configuration.registries from Bicep to avoid the circular dependency, the Container App still needs registry configuration for private ACR images; please reword to say that AZD (during azd deploy) configures the registry/identity outside the template, and mention the manual equivalent for non-AZD flows.

// Placeholder image allows provisioning before app image exists in ACR.
// No registries block in Bicep — azd deploy configures the registry/identity link
// (az containerapp registry set --identity system) and updates the image via the Azure API.

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:33

• Similar to the earlier note: saying “a registries block is not required” can be misleading because the Container App still must have registry configuration to pull from private ACR. Consider tightening this to “not required in this template because AZD configures registry access during deploy”, and add a pointer for non-AZD deployments (e.g., az containerapp registry set).

        transport: 'auto'
      }

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:99

• The phrase “No registries param — AZD handles image update after provisioning” could be interpreted as AZD only updates the image, but registry auth is the other required piece for private ACR pulls. Please clarify in this wiring example that AZD also configures the Container App registry binding/identity (or document the manual equivalent) before switching to an ACR image.

module api './modules/container-app.bicep' = {
  name: 'api'
  scope: rg
  params: {
    containerImageName: 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'

• Files reviewed: 5/5 changed files
• Comments generated: 1

[fanyang-mono]

@copilot Bump Skill 'azure-deploy' to 1.0.17.
Bump Skill 'azure-prepare' to 1.1.10

[Copilot]

@copilot Bump Skill 'azure-deploy' to 1.0.17.
Bump Skill 'azure-prepare' to 1.1.10

Done in 126f2b1 — azure-deploy bumped to 1.0.17 and azure-prepare bumped to 1.1.10.

[Copilot]

Pull request overview

Updates the Azure Container Apps + ACR Bicep guidance to standardize on a two-phase deployment pattern that avoids the AcrPull role-assignment circular dependency, and aligns azure-deploy troubleshooting/docs with the new flow.

Changes:

• Replaces prior Container Apps registry auth patterns with a canonical two-phase module approach (placeholder image + MI first, AcrPull module second).
• Updates deployment guidance and error docs to reflect RBAC propagation behavior under the two-phase approach.
• Bumps skill metadata versions for azure-prepare and azure-deploy.

Show a summary per file

File	Description
plugin/skills/azure-prepare/SKILL.md	Bumps azure-prepare skill version metadata.
plugin/skills/azure-prepare/references/services/container-apps/bicep.md	Documents the two-phase Container Apps + ACR pattern and provides example module wiring.
plugin/skills/azure-deploy/SKILL.md	Bumps azure-deploy skill version metadata.
plugin/skills/azure-deploy/references/recipes/azd/errors.md	Updates the “Container App Revision Timeout” cause steps to reference the two-phase pattern.
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	Updates the RBAC health-check section to reflect placeholder-image provisioning and two-phase role assignment.

Copilot's findings

Comments suppressed due to low confidence (1)

plugin/skills/azure-prepare/references/services/container-apps/bicep.md:22

• This Bicep snippet now uses appName for the Container App name but doesn’t define it in the snippet (and it’s a new symbol compared to the previous inline interpolation). Add a param appName string (or show the naming expression) so the sample is self-contained and unambiguous.

param containerImageName string = 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'

resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  name: appName
  location: location

• Files reviewed: 5/5 changed files
• Comments generated: 3

[Copilot]

The PR description says the version bumps are azure-prepare 1.1.8→1.1.9 and azure-deploy 1.0.15→1.0.16, but this change bumps azure-prepare from 1.1.9→1.1.10. Please update the PR description to match the actual versions (or adjust the version bump if the description is the intended target).

[Copilot]

The PR description says azure-deploy should bump 1.0.15→1.0.16, but this change bumps 1.0.16→1.0.17. Please reconcile the PR description vs the actual version bump so consumers know what’s being released.

[Copilot]

This tip references az containerapp registry set --identity system, but that’s not a complete runnable command (it requires --name and --resource-group, and typically --server <acr-login-server>). Consider either expanding it to the full command with placeholders or clarifying it’s shorthand for the registry/identity-link step.

Suggested change

> 💡 **Two-phase Bicep pattern:** With the recommended two-phase deployment pattern, `azd provision` succeeds immediately because the Container App is provisioned with a public placeholder image (not an ACR image). The AcrPull role assignment is deployed in a separate module with no circular dependency. `azd deploy` then configures the registry/identity link (`az containerapp registry set --identity system`) and pushes the real image via the Azure API — but the AcrPull role still needs time to propagate before this succeeds.

> 💡 **Two-phase Bicep pattern:** With the recommended two-phase deployment pattern, `azd provision` succeeds immediately because the Container App is provisioned with a public placeholder image (not an ACR image). The AcrPull role assignment is deployed in a separate module with no circular dependency. `azd deploy` then configures the registry/identity link (the equivalent CLI step is `az containerapp registry set --name <app-name> --resource-group rg-<environment-name> --server <acr-login-server> --identity system`) and pushes the real image via the Azure API — but the AcrPull role still needs time to propagate before this succeeds.