Skip to content

Make extension registry updates resilient to coordinated multi-extension version bumps#8927

Draft
JeffreyCA wants to merge 7 commits into
Azure:mainfrom
JeffreyCA:jeffreyca/ext-snapshot-fixes
Draft

Make extension registry updates resilient to coordinated multi-extension version bumps#8927
JeffreyCA wants to merge 7 commits into
Azure:mainfrom
JeffreyCA:jeffreyca/ext-snapshot-fixes

Conversation

@JeffreyCA

@JeffreyCA JeffreyCA commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Fixes #8924

This PR makes extension registry updates resilient when several interdependent extensions are released at the same time.

The problem

When we recently bumped all the azure.ai.* extension versions together (#8896) and kicked off the per-extension release pipelines in parallel, every pipeline failed at the "Refresh Fig/Usage snapshots" step.

The root cause is that this step installs every extension from the in-repo registry.json through the full, dependency-resolving install path, and fails on the first error. But each pipeline rewrites only its own registry entry against the current tip of main, so the registry under test was transiently inconsistent. That produced failures such as:

  • dependency azure.ai.inspector required by azure.ai.agents was not found
  • installed dependency azure.ai.connections version 1.0.0-beta.1 does not satisfy constraint "~0.1.0-preview"

We ended up reconciling the registry by hand. This PR closes the two gaps behind that outcome.

Change 1: decouple snapshot generation from dependency resolution

What this means: the ADO extension release pipeline should no longer fail on "Update_Registry - Refresh Fig/Usage snapshots", when the registry is momentarily inconsistent during multi-extension version bumps.

Command snapshots only need each extension's own binary so its commands register. They do not need the registry's dependency graph to be internally consistent.

  • Adds a --no-dependencies flag to azd extension install that installs only the named extension, without resolving or installing its declared dependencies and without enforcing the installed-dependency version constraints.
  • The Fig/Usage snapshot helper now uses it, so each extension installs independently of whatever versions its siblings happen to be at.
  • The flag is honored on both the fresh-install and the reinstall/upgrade paths, so it behaves consistently whether or not the extension is already installed.
  • It is opt-in: a normal azd extension install <id> still installs the full dependency graph exactly as before.
  • Nothing is dropped from the snapshot, because every extension that ships a binary is also a top-level registry entry installed on its own, and the artifact-less microsoft.foundry meta-package contributes no commands.

Change 2: cross-dependency registry validation

What this means: a genuinely broken registry (a dependency pinned to a version that was never published) is blocked at PR time (not during release pipeline) with a clear, actionable message, instead of slipping through and breaking installs for users. Warnings and mid-rollout publishing are not blocked, so routine releases are unaffected.

Registry validation previously checked per-extension fields but never verified that a declared dependency could actually be resolved, so an inconsistent registry only surfaced as a cryptic install failure inside a snapshot test.

  • The validator now checks every declared dependency against the versions the registry actually publishes, reusing the same version-constraint matcher the installer uses so validation mirrors install-time resolution.
  • An unsatisfiable constraint is an error (it can never be resolved); an entirely absent dependency id is a warning (it may be provided by another registered source).
  • A new TestRegistryFileIsValid test runs in the ext-registry-ci workflow, which triggers on any pull request that changes registry.json, so the automated per-extension registry-update PRs are gated on it.
  • It fails only on errors, never warnings, and its output names the exact extension, constraint, and available versions, turning a genuine inconsistency into an early, readable failure on the PR instead of a silent one that ships.

Updating microsoft.foundry before all dependencies are updated:

image

Passing registry consistency but failing snapshot tests:

image

Successful run:

image

Behavior at a glance

Scenario Before After
"Refresh Fig/Usage snapshots" step during a coordinated multi-extension bump Fails on the first extension whose dependency graph is transiently inconsistent, blocking the registry update Each extension installs independently via --no-dependencies; the step no longer depends on registry-wide consistency
azd extension install <id> (no flag), end user Installs the extension and its declared dependencies Unchanged
azd extension install <id> --no-dependencies Flag did not exist Installs only the named extension; dependencies are neither resolved, installed, nor constraint-checked, on both fresh install and reinstall/upgrade
Registry with a dependency constraint no published version can satisfy Surfaces later as a cryptic install failure inside a snapshot test Reported as a validation error on any PR that changes registry.json, naming the extension, constraint, and available versions
Registry with a dependency id absent from the registry Not detected by validation Reported as a validation warning (the dependency may be provided by another source)
azd x publish while a single extension is mid-rollout Publishes the entry Unchanged: publishing does not run registry validation, so legitimately transient states are not blocked

Testing

  • Added unit coverage for skipping dependencies on both fresh install and upgrade, and for bypassing the installed-dependency constraint check.
  • Added validator coverage for the satisfied, unsatisfiable-as-error, absent-as-warning, and empty-constraint cases, plus the production-registry gate.
  • Regenerated the Fig and Usage command snapshots to include the new flag.
  • The existing extension suite, gofmt, and golangci-lint all pass.

JeffreyCA added 2 commits July 1, 2026 18:45
Add a --no-dependencies flag to `azd extension install` and cross-dependency
registry validation so parallel per-extension release pipelines no longer fail
at the "Refresh Fig/Usage snapshots" step when interdependent extensions are
bumped together.

The snapshot step installs every extension from registry.json through the full
dependency-resolving path, but each pipeline rewrites only its own entry against
main, so the registry is transiently inconsistent during a coordinated bump.
--no-dependencies installs only the named extension, without resolving or
installing declared dependencies and without enforcing installed-dependency
constraints, on both the fresh-install and reinstall/upgrade paths. The snapshot
helper uses it; a normal install is unchanged. Nothing is dropped from the
snapshot because every binaried dependency is also a top-level registry entry.

Registry validation now checks every declared dependency against published
versions using the installer's constraint matcher: an unsatisfiable constraint
is an error, an absent dependency id is a warning. A new TestRegistryFileIsValid
gate catches inconsistency at PR time instead of inside a snapshot test.
@JeffreyCA

JeffreyCA commented Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

Updating microsoft.foundry before all dependencies are updated:

image

Passing registry consistency but failing snapshot tests:

image

@github-actions github-actions Bot added area/extensions Extensions (general) ext-foundry azure.ai.{agents,connections,inspector,projects,routines,skills,toolboxes}, microsoft.foundry labels Jul 1, 2026
@JeffreyCA JeffreyCA force-pushed the jeffreyca/ext-snapshot-fixes branch from bfe3d50 to 351477d Compare July 1, 2026 20:58
@github-actions github-actions Bot added the ext-agents azure.ai.agents extension label Jul 1, 2026
@JeffreyCA JeffreyCA force-pushed the jeffreyca/ext-snapshot-fixes branch from 351477d to 9d8fb90 Compare July 1, 2026 21:12
@JeffreyCA JeffreyCA force-pushed the jeffreyca/ext-snapshot-fixes branch from 9d8fb90 to edf5fc4 Compare July 1, 2026 21:15
@github-actions github-actions Bot added ext-connections azure.ai.connections extension ext-inspector azure.ai.inspector extension labels Jul 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/extensions Extensions (general) ext-agents azure.ai.agents extension ext-connections azure.ai.connections extension ext-foundry azure.ai.{agents,connections,inspector,projects,routines,skills,toolboxes}, microsoft.foundry ext-inspector azure.ai.inspector extension

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Extension releases: decouple Fig/Usage snapshot generation from registry dependency resolution, and add cross-dependency registry validation

1 participant