Repository navigation
Document configuration sources and CLI options - #2102
Conversation
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
2c65b12 to
c0523c5
Compare
There was a problem hiding this comment.
🔵 Needs a closer look
The new workflows were checked against source, but browser rendering and end-to-end CLI validation remain unverified because the review environment lacked dependencies.
No open issues 🎉
What changed in this PR
This PR documents Git-hosted configuration sources for sharing organization-specific Aspire defaults and connects the new guide to the CLI reference and site navigation.
Changes:
- Add guidance for using and publishing configuration sources, including trust, opt-outs, saved bindings, content pins, and distribution.
- Document
--use-config-sourcefornew,init, andupdate, plus refresh-onlyupdate --config-sourcebehavior. - Update non-interactive creation guidance and add command examples.
| File | Description |
|---|---|
src/frontend/src/content/docs/reference/cli/configuration.mdx |
Link to the configuration sources guide. |
src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx |
Explain source adoption, refresh-only updates, and consent behavior. |
src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx |
Document source selection and non-interactive creation requirements. |
src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx |
Document source consent and preservation of existing bindings. |
src/frontend/src/content/docs/extensibility/config-sources.mdx |
Add the guide for consuming, securing, and publishing shared defaults. |
src/frontend/config/sidebar/docs.topics.ts |
Add the guide to the extensibility navigation. |
Review effort: Balanced
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
Documentation accuracy review
Phase A source: microsoft/aspire, release/17.0 at cec195f2d0bf3f1d714badf74f205fa855fdf963. Community Toolkit and Azure SDK sources were not needed. 28 non-narrative claims: 27 verified, 1 contradicted, 0 verified with nuance, 0 unverifiable.
Phase B tester: Exercised /extensibility/config-sources/, /reference/cli/commands/aspire-init/, /reference/cli/commands/aspire-new/, /reference/cli/commands/aspire-update/, /reference/cli/configuration/, plus /get-started/install-cli/ and /reference/cli/overview/ on local PR head 1bdbf2f83dd340f3751e0da179f3ef346581fbc0 at http://localhost:4322/. All rendered; 0 critical issues and 1 warning (the installed CLI build lacks the documented options, so command examples could not be executed against a matching build).
Phase A — Claim verification
One contradicted claim is noted inline. The remaining claims were verified against microsoft/aspire at the source revision above:
Verified claims (27)
- Consent flow shows the configured source details and trust warning, and prompts when interactive —
src/Aspire.Cli/Configuration/ConfigSourceService.cs:149-206. - Accept/decline is controlled by
--use-config-source; an explicit acceptance without a candidate is an error —ConfigSourceService.cs:47-50,149-205. - Declining writes an app-local
configSource.optOutwithout undoing previously applied settings —ConfigSourceService.cs:202-205,258-278. aspire update --use-config-sourcecan adopt a source for an app without a binding while continuing normal project updates; existing bindings/opt-outs are preserved —ConfigSourceService.cs:231-250;src/Aspire.Cli/Commands/UpdateCommand.cs:303.- The supported source sections are
skillSources,integrationSources, andtemplateSources—ConfigSourceService.cs:28;src/Aspire.Cli/Configuration/AspireConfigFile.cs:121-129;src/Aspire.Cli/Packaging/IntegrationSourceConfiguration.cs:13-16. - Skills and integration-source settings are materialized in the app configuration, while template sources are runtime discovery inputs —
ConfigSourceService.cs:280-315,352-408;src/Aspire.Cli/Templating/ConfiguredTemplateSourceService.cs:20-35. - Only supplied skill/integration sections are applied; unrelated source settings are not imported —
ConfigSourceService.cs:28,352-397. - Applying settings does not itself acquire every skill, package, or template; skill registration is separate from content acquisition —
src/Aspire.Cli/Agents/AspireSkills/AspireSkillsRemoteConfiguration.cs:195-225;src/Aspire.Cli/Packaging/IntegrationSourceConfiguration.cs:22-34. - Built-in skill and integration defaults remain enabled unless their
defaultentries are disabled/overridden —src/Aspire.Cli/Agents/AspireSkills/SkillSource.cs:25-35;IntegrationSourceConfiguration.cs:13-16,55-82. - These are defaults rather than enforcement; normal environment/global/local configuration resolution remains in effect —
ConfigSourceService.cs:183-185;SkillSource.cs:61-65;IntegrationSourceConfiguration.cs:39-46. - The saved binding fields and app-local configuration location match the example —
src/Aspire.Cli/Configuration/ConfigSource.cs:11-31;AspireConfigFile.cs:60-71. - A missing ref resolves to
HEAD(the repository default branch), and a commit ref selects that commit;appliedVersionstores the selected configuration blob ID —ConfigSource.cs:34-40;ConfigSourceService.cs:752-785,352-385. - Existing bindings are read from the nearest app configuration; initialization does not silently retarget them from changed environment settings —
ConfigSourceService.cs:210-224,231-242. - Project checks are advisory and report when a newer source is available rather than applying it —
ConfigSourceService.cs:56-85,412-459. - Forced refresh fetches the saved selector: a branch/default ref can advance, while a full commit remains pinned —
ConfigSourceService.cs:412-458,752-785;ConfigSource.cs:34-40. - After a pin changes, refresh records the newly read blob ID as
appliedVersion—ConfigSourceService.cs:352-385. - A supplied skill/integration section replaces that section, including local entries; omitted sections remain unchanged —
ConfigSourceService.cs:352-397. - Refresh does not run package/CLI/SDK updates or regenerate templates; it applies the bound configuration through the refresh-only update path —
src/Aspire.Cli/Commands/UpdateCommand.cs:52-54,206-215;ConfigSourceService.cs:412-458. - HTTPS, SSH, SCP-style SSH, and fully qualified local repository paths are accepted; relative paths and
file://URLs are not —src/Aspire.Cli/Git/GitHelpers.cs:8-46;ConfigSource.cs:50-68. - The repository URL validator rejects embedded HTTPS credentials; Git is invoked for acquisition, using configured Git authentication —
GitHelpers.cs:22-34;ConfigSourceService.cs:752-785. - A shared file cannot recursively declare its own
configSource—ConfigSourceService.cs:694-714. - Integration patterns constrain package discovery, and patterns for entries resolving to the same feed are combined —
src/Aspire.Cli/Packaging/IntegrationSourceConfiguration.cs:22-34,86-124. - Configuration/skill refs accept branch selectors or full commit IDs, not abbreviated hashes or tag selectors —
src/Aspire.Cli/Git/GitHelpers.cs:48-62;ConfigSource.cs:34-40. - The implemented initialization-source variables are
ASPIRE_INIT_SOURCE_URL,_PATH, and_REF; path defaults toaspire.config.json, and an unset ref uses the repository default —src/Aspire.Cli/CliConfigNames.cs:9-13;ConfigSourceService.cs:153-179,322-327. - An explicit source URL takes precedence over employee detection; path/ref overrides are read only for an explicitly configured URL —
ConfigSourceService.cs:153-179,291-306. - An explicit initialization-source URL can contribute a runtime template-discovery overlay; employee detection alone does not —
ConfigSourceService.cs:280-315. - Distributing the environment settings makes a source available but does not itself accept it or mutate existing app bindings —
ConfigSourceService.cs:149-206,210-245.
Phase B — Doc-tester results
Focus area: Configuration-source guide and affected CLI/configuration references. PR ref served: 1bdbf2f83dd340f3751e0da179f3ef346581fbc0 at http://localhost:4322/.
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content accuracy | 0 | 0 | 0 |
| Code examples | 0 | 0 | 1 |
| CLI commands | 0 | 0 | 1 |
| Links/routes | 7 | 0 | 0 |
Critical issues
None.
Warnings
- The available CLI is
17.0.0-preview.1.26509.1+6554654b8613940a1a973f03bf464b7379075f5a; itsinit,new, andupdatehelp output does not list the documented--use-config-source/--config-sourceoptions. The pages render correctly, but I could not execute their command examples with this local binary or determine whether the mismatch is only a build-version skew.
Passed checks
- The new configuration-source page and all four modified CLI/configuration routes rendered with the expected titles and relevant sections/options visible.
- The install-CLI and CLI-overview routes linked from the guide also loaded.
- No broken routes were observed in the exercised pages.
Recommendations
- Re-run the command examples with a CLI build that includes the documented configuration-source options.
Knowledge gaps
- Command behavior remains untested because the installed preview CLI did not expose the options described by the PR. No implementation assumptions were used to fill that gap.
Superseded by subsequent updates; requesting a fresh review.
bbc2c47 to
a60653c
Compare
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
a60653c to
a1e09ca
Compare
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2a90c00
into
release/17.0
Summary
/extensibility/config-sources/, organized around using a source and creating one.--use-config-sourcefornew,init, andupdate, plus refresh-onlyupdate --config-sourcebehavior and examples.Validation