You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Implement project-bound Git configuration sources for Aspire CLI - #20805
Implements project-bound Git configuration sources for the Aspire CLI so organizations can share approved defaults without changing SDK/channel identity or making a remote repository a runtime configuration provider.
Users can accept a proposed source during aspire new or aspire init. The CLI acquires and validates a Git snapshot, copies only allowlisted documentation settings into the application's aspire.config.json, and saves a configSource binding. Normal commands continue using saved application settings; source checks are advisory and never silently apply changes.
Implemented behavior
Select candidates from ASPIRE_INIT_SOURCE_URL, with optional repository-relative ASPIRE_INIT_SOURCE_PATH and branch/full-commit ASPIRE_INIT_SOURCE_REF, or the Microsoft default when the existing employee detector identifies an internal user. Detection supplies a default, not consent or authorization.
Require explicit consent before acquisition. Non-interactive creation uses --use-config-source true or false; an existing binding is reused without repeating consent, detection, or retargeting from the current environment.
Materialize only docs.llmsTxtUrl and docs.api.sitemapUrl. Preserve unrelated project settings, normalize supported flat/nested keys case-insensitively, and retain existing nested values when normalization encounters a conflicting flat key.
Keep bindings local to the configuration file that declares them. Materialized parent settings still inherit normally, but child projects do not inherit a parent's source binding or refresh its file. C# solution-mode init explicitly selects the solution-root configuration rather than creating a second binding under the generated AppHost.
Add aspire update --config-source to explicitly fetch and apply source settings, replacing local edits only at supplied allowlisted leaves. Explicit AppHost directories are resolved before configuration-only fallback.
Run due version checks in the background for resolved source-bound projects, using a 24-hour successful-check cadence. Defer completed notices/warnings until command exit, suppress them for machine-readable output, and cancel/join unfinished checks without blocking the foreground operation on remote acquisition.
Use normal Git authentication. Interactive fetches inherit terminal input/output so credential helpers can interact with the user. Unattended fetches disable Git terminal and GCM prompts; configured SSH launchers are preserved and can still prompt, with the two-minute timeout bounding the operation.
Preserve partial captured Git output on timeout and display only its final 64 Ki characters on stderr. Do not display configuration-file contents or put captured diagnostics into exception messages, logs, or telemetry. Bound process-tree shutdown and output draining.
Retain only the latest successfully fetched source snapshot and separate advisory-check metadata under Aspire home. Use locking and atomic writes, preserve destination permissions, and tolerate incomplete bindings during general settings loading while rejecting them when the source is used.
Wire saved documentation URLs into documentation acquisition/cache behavior, add focused regression tests, document the implementation and first-party scenarios, and add VS Code CLI debugging tasks/configuration.
Detailed source-driven skills, templates, integration acquisition, and their content schema remain proposed follow-up work; they are not implemented by this PR.
Decline a proposed source with --use-config-source false. Subsequent commands use the saved binding, not the current initialization environment variables.
Relevant command-help options:
aspire init:
--use-config-source Accept or decline the proposed Git configuration source for this project.
aspire update:
--config-source Apply allowed settings from the project's saved Git configuration source,
replacing local edits to supplied settings, without updating packages or the CLI.
--apphost <apphost> The path to the Aspire AppHost project file or a directory to search
Screenshots / Recordings
This PR includes CLI interaction changes. TODO: add a recording of accepting/declining a proposed configuration source, interactive Git authentication, explicit refresh, and a deferred update/timeout notice. No screenshots or recordings have been uploaded.
Security considerations
This implementation makes outbound Git connections, invokes Git and its credential helpers, reads untrusted repository JSON, and writes application configuration and private tracking data under Aspire home. It validates repository addresses, repository-relative paths, refs, JSON shape, and allowlisted settings; rejects symlink configuration entries; and limits configuration files to 4 MiB. Remote data cannot select AppHost paths, SDK/channel settings, arbitrary features, or another configuration source.
Employee detection does not grant access. Authentication remains Git's responsibility. Unattended SSH prompting is an accepted limitation bounded by timeout, not a guarantee of prompt-free SSH. Interactive Git output and timeout-only diagnostics can contain private repository/authentication details and must not enter ordinary logs or telemetry. Formal threat modeling and security review remain outstanding.
Validation
Executed on Windows against the latest implementation:
Passed before committing the solution-root initialization fix.
The full repository suite, CLI terminal E2E scenarios, and interactive authentication recordings were not run as part of this update. An earlier broader CLI run encountered GuestAppHostProjectTests.RunAsync_SignalsBuildCompletionAfterGuestAppHostLaunches, which was also reproduced on the main-branch baseline.
Fixes # (issue)
Checklist
Is this feature complete?
Yes. Ready to ship.
No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
Yes
No
Did you add public API?
Yes
If yes, did you have an API Review for it?
Yes
No
Did you add <remarks /> and <code /> elements on your triple slash comments?
Yes
No
No
Does the change make any security assumptions or guarantees?
Yes
If yes, have you done a threat model and had a security review?
James Newton-King (JamesNK)
changed the title
Add CLI config sources design spec
Specify project-bound remote configuration sources for Aspire CLI
Oct 20, 2026
Addressed Mitch Denny (@mitchdenny)'s force-refresh feedback in b3a92a4. The spec now defines aspire update --config-source as a refresh-only mode that bypasses the 24-hour cache window, uses the saved project binding, and leaves CLI/packages/content unchanged. It also covers project selection, non-interactive usage, incompatible options, failure/cancellation handling, and implementation validation.
Validation: git diff --check -- docs/specs/cli-config-sources.md passed; no tests run (documentation-only change).
Keep the source-bound configuration at the project root while moving the file-based AppHost and its run settings into a child directory for ancestor notification and refresh scenarios.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Align source checks and refreshes with settings discovery, preserve each binding's file path, and cover local/global source behavior. Share the source section name, use 30-second Git timeouts, and clarify command lifecycle behavior.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Recognize target-local legacy bindings during initialization without inheriting ancestor bindings. Serialize global configuration mutations with source refresh and add regression coverage for both fixes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Restore constructor-time documentation service initialization, make unbound refresh an informational no-op, and clarify configuration source messages and error classification. Update related documentation, localization, and existing test expectations. Reuse shared PID-file polling to fix the process-shutdown test race on Windows.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Use the existing long timeout for the real multi-file update transaction while preserving all persistence and rollback assertions.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Validate explicit file and directory targets before resolving configuration sources. Preserve existing-directory fallback, document the behavior, and add regression coverage that verifies local and global bindings remain untouched.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both acquisition and advisory checks are cancelled after 30 seconds, rather than the two-minute timeout specified in the PR description and documented below. This also limits interactive credential-helper/MFA completion to 30 seconds, causing otherwise successful authentication or slower fetches to fail prematurely. Use the documented two-minute budget for these operations.
Use one root-only normalizer for local and source settings, normalize source JSON before provider validation, and reject merged duplicate paths before writing. Update regression coverage and the configuration source specification.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Select and refresh configuration sources using the AppHost's effective configuration file while preserving template settings and parent configuration.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Git authentication and untrusted configuration persistence still require the acknowledged human security review and terminal end-to-end validation.
No open issues 🎉
1 previously missed issue
In code that hasn't changed since last review
Launch configuration creates a project instead of showing help
docs/contributing.md:232
The checked-in launch configuration passes new, not --help (.vscode/launch.json:11–13). Following these debugging instructions therefore starts project creation rather than showing help. Please describe the actual default, or change the launch arguments to --help if a non-mutating default is intended.
Accept normal channel completion or cancellation during watcher shutdown while continuing to reject duplicate connection snapshots.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Git authentication, untrusted configuration processing, and persistent settings changes still need human security review and terminal end-to-end validation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Implements project-bound Git configuration sources for the Aspire CLI so organizations can share approved defaults without changing SDK/channel identity or making a remote repository a runtime configuration provider.
Users can accept a proposed source during
aspire neworaspire init. The CLI acquires and validates a Git snapshot, copies only allowlisted documentation settings into the application'saspire.config.json, and saves aconfigSourcebinding. Normal commands continue using saved application settings; source checks are advisory and never silently apply changes.Implemented behavior
ASPIRE_INIT_SOURCE_URL, with optional repository-relativeASPIRE_INIT_SOURCE_PATHand branch/full-commitASPIRE_INIT_SOURCE_REF, or the Microsoft default when the existing employee detector identifies an internal user. Detection supplies a default, not consent or authorization.--use-config-source trueorfalse; an existing binding is reused without repeating consent, detection, or retargeting from the current environment.docs.llmsTxtUrlanddocs.api.sitemapUrl. Preserve unrelated project settings, normalize supported flat/nested keys case-insensitively, and retain existing nested values when normalization encounters a conflicting flat key.initexplicitly selects the solution-root configuration rather than creating a second binding under the generated AppHost.aspire update --config-sourceto explicitly fetch and apply source settings, replacing local edits only at supplied allowlisted leaves. Explicit AppHost directories are resolved before configuration-only fallback.Detailed source-driven skills, templates, integration acquisition, and their content schema remain proposed follow-up work; they are not implemented by this PR.
User-facing usage
Decline a proposed source with
--use-config-source false. Subsequent commands use the saved binding, not the current initialization environment variables.Relevant command-help options:
Screenshots / Recordings
Security considerations
This implementation makes outbound Git connections, invokes Git and its credential helpers, reads untrusted repository JSON, and writes application configuration and private tracking data under Aspire home. It validates repository addresses, repository-relative paths, refs, JSON shape, and allowlisted settings; rejects symlink configuration entries; and limits configuration files to 4 MiB. Remote data cannot select AppHost paths, SDK/channel settings, arbitrary features, or another configuration source.
Employee detection does not grant access. Authentication remains Git's responsibility. Unattended SSH prompting is an accepted limitation bounded by timeout, not a guarantee of prompt-free SSH. Interactive Git output and timeout-only diagnostics can contain private repository/authentication details and must not enter ordinary logs or telemetry. Formal threat modeling and security review remain outstanding.
Validation
Executed on Windows against the latest implementation:
Passed: 489 tests; 10 platform-specific tests skipped; 0 failures. Coverage includes source consent/selection, real Git acquisition and cancellation, timeout diagnostics, advisory checks, explicit refresh, allowlisted merges, incomplete bindings, project selection, non-inherited bindings, solution-root initialization, and configuration persistence.
Passed before committing the solution-root initialization fix.
The full repository suite, CLI terminal E2E scenarios, and interactive authentication recordings were not run as part of this update. An earlier broader CLI run encountered
GuestAppHostProjectTests.RunAsync_SignalsBuildCompletionAfterGuestAppHostLaunches, which was also reproduced on the main-branch baseline.Fixes # (issue)
Checklist
<remarks />and<code />elements on your triple slash comments?