Skip to content

Support config source adoption and explicit project opt-out - #21678

Merged
James Newton-King (JamesNK) merged 3 commits into
mainfrom
jamesnk/config-source-brownfield
Nov 2, 2026
Merged

James Newton-King (JamesNK) merged 3 commits into
mainfrom
jamesnk/config-source-brownfield

Conversation

@JamesNK

Copy link
Copy Markdown
Member

Description

Existing AppHosts have no opportunity to adopt an available organization configuration source unless they are recreated. This adds opt-in adoption to aspire update and persists an explicit project opt-out so declining does not cause repeated prompts.

PR stack: main -> this brownfield PR -> doctor diagnostics in #21677. The doctor PR targets this branch; it is not included in this PR's diff.

  • Offer the existing configuration-source consent prompt during project updates when a candidate exists and the nearest local configuration has neither a saved binding nor an opt-out.
  • Accepting materializes the existing allowlisted settings and records the source binding; declining saves "configSource": { "optOut": true } while preserving other project settings.
  • Persist the same opt-out when a source is declined during aspire new or aspire init.
  • Preserve existing unattended automation: without --use-config-source, non-interactive updates skip adoption without writing an opt-out. --yes alone is not consent to configuration-source adoption.
  • Keep saved bindings authoritative. CLI self-update, repository-tool-only updates, and refresh-only aspire update --config-source do not discover or adopt sources. A local opt-out does not prevent refreshing a separate global binding.

User-facing usage

With an available source and no saved choice, run aspire update to accept or decline interactively. To make the choice explicitly in automation:

aspire update --yes --non-interactive --use-config-source
aspire update --yes --non-interactive --use-config-source false

Relevant generated help from the built CLI:

Usage:
  aspire update [options]

Options:
  --use-config-source  Use the proposed Git configuration source. Specify false to decline it.

Declining records this project choice alongside existing settings:

{
  "configSource": {
    "optOut": true
  }
}

An existing binding or opt-out suppresses adoption, including when --use-config-source is supplied. Remove the configSource entry to allow a later adoption prompt.

Screenshots / Recordings

This PR includes UI changes. Please add screenshots or screen recordings so reviewers can evaluate the visual changes without running locally.

  • For before/after comparisons, place them side-by-side or label them clearly.
  • For interactive changes (animations, transitions, new flows), prefer a short screen recording (GIF or video).
  • If you cannot capture visuals now, note what scenario to test and mark this section as TODO.

TODO: Capture aspire update in an existing AppHost with an available source and no saved choice. Show the consent prompt, acceptance, and declining followed by a second update without another adoption prompt. No visual capture was made during this change.

Security considerations

This makes the existing Git acquisition and configuration materialization flow available during project updates. Environment variables and employee detection provide candidates, not consent; unattended package updates and --yes must not silently enable a source. Accepted sources continue through the existing validation and setting allowlist. Opt-outs are written using the workspace configuration lock and atomic settings writer. A separate threat model and security review have not been performed for this change.

Validation

Brownfield regression tests run earlier in this session, before the doctor changes were added: passed, 915 succeeded, 0 failed, 2 skipped.

$env:MSBUILDTERMINALLOGGER='false'
dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ConfigSourceServiceTests" --filter-class "*.ConfigSourceCommandTests" --filter-class "*.NewCommandLocalTemplateTests" --filter-class "*.UpdateCommandTests" --filter-class "*.AspireConfigFileTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"

Brownfield-only diff whitespace validation: passed.

git diff --check origin/main...jamesnk/config-source-brownfield

Generated update help checked using the current built CLI: passed.

dotnet artifacts\bin\Aspire.Cli\Debug\net11.0\aspire.dll update --help

No additional test run was needed for PR creation. The full repository suite and manual visual verification were not run.

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?
        • Yes
        • No
    • No

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21678

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21678"

@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The consent test still expects no configSource after opt-out is persisted, and update-time lookup can miss unnormalized colon-separated settings, prompting again and overwriting saved choices.

2 open issues
What changed in this PR

Adds configuration-source adoption to existing AppHosts through aspire update and persists explicit project opt-outs. This provides the foundation for the separate doctor diagnostics in #21677.

Changes:

  • Offers consent-based adoption during project updates while preserving unattended behavior and saved choices.
  • Persists declined choices across new, init, and update without acquiring the source.
  • Adds regression tests, snapshots, and documentation for adoption and opt-out behavior.
File Description
tests/​Aspire.Cli.Tests/​Snapshots/​NewCommandLocalTemplateTests.InitConfigSources_SearchAndGenerateWithGlobalSourcesWithoutPersistingInheritedSources_materialize=True.verified.json Captures accepted-source materialization.
tests/​Aspire.Cli.Tests/​Snapshots/​NewCommandLocalTemplateTests.InitConfigSources_SearchAndGenerateWithGlobalSourcesWithoutPersistingInheritedSources_materialize=False.verified.json Captures persisted opt-out.
tests/​Aspire.Cli.Tests/​Snapshots/​ConfigSourceServiceTests.Materialize_OptOutPreservesProjectSettingsWithoutAcquisition.verified.json Captures settings preservation when declining.
tests/​Aspire.Cli.Tests/​Configuration/​ConfigSourceServiceTests.cs Tests opt-outs, global refresh independence, and failure preservation.
tests/​Aspire.Cli.Tests/​Commands/​NewCommandLocalTemplateTests.InitConfig.cs Uses snapshots to verify saved source choices.
tests/​Aspire.Cli.Tests/​Commands/​ConfigSourceCommandTests.cs Tests update adoption, repeated invocations, unattended updates, and creation choices.
src/​Aspire.Cli/​Configuration/​ConfigSourceService.cs Implements adoption, opt-out persistence, and skipped source operations for opt-outs.
src/​Aspire.Cli/​Configuration/​ConfigSource.cs Adds serialized opt-out state and identity comparison.
src/​Aspire.Cli/​Configuration/​AspireConfigFile.cs Updates the configuration-source property description.
src/​Aspire.Cli/​Commands/​UpdateCommand.cs Registers consent options and invokes project adoption.
docs/​specs/​cli-config-sources.md Documents adoption, persisted choices, and automation behavior.
docs/​specs/​cli-config-sources-1p-scenarios.md Updates user scenarios for adoption and opt-outs.

Review effort: Balanced

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment has been minimized.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Tests selector

2 / 100 PR test projects · 4 PR jobs, from 12 changed files.

Selected PR test projects (2 / 100)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

📦 affected project Aspire.Cli
→ 1 test: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/ConfigSourceTests.cs (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/Helpers/ConfigSourceTestContext.cs (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.Tests/Commands/ConfigSourceCommandTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Commands/NewCommandLocalTemplateTests.InitConfig.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Configuration/ConfigSourceServiceTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/ConfigSourceServiceTests.Materialize_OptOutPreservesProjectSettingsWithoutAcquisition.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/NewCommandLocalTemplateTests.InitConfigSources_SearchAndGenerateWithGlobalSourcesWithoutPersistingInheritedSources_materialize=False.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Snapshots/NewCommandLocalTemplateTests.InitConfigSources_SearchAndGenerateWithGlobalSourcesWithoutPersistingInheritedSources_materialize=True.verified.json (changed test)
→ 1 directly: Aspire.Cli.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Cli
extension-e2e • src/Aspire.Cli/Commands/UpdateCommand.cs, src/Aspire.Cli/Configuration/AspireConfigFile.cs, src/Aspire.Cli/Configuration/ConfigSource.cs, src/Aspire.Cli/Configuration/ConfigSourceService.cs
• affected project Aspire.Cli
polyglot affected project Aspire.Cli
typescript-api-compat affected project Aspire.Cli

Selection computed for commit 11b7ef9.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The opt-out setting is excluded from the configuration schema and fails validation, while the new consent flow lacks terminal E2E coverage for saved choices and unattended behavior.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Add CLI coverage for update consent and unattended behavior

src/​Aspire.Cli/​Commands/​UpdateCommand.cs:303

The new plain aspire update consent flow has no terminal E2E coverage in ConfigSourceTests, leaving its prompt sequence and unattended behavior unverified through the real CLI. Add scenarios that accept and decline adoption in an existing AppHost, then run update again to verify that the saved choice suppresses the prompt. Also cover --yes --non-interactive without explicit source consent and verify that it neither prompts nor writes a source choice.

Medium severity Expose configSource.optOut in the generated settings schema

src/​Aspire.Cli/​Configuration/​ConfigSource.cs:16

SettingsSchemaBuilder.BuildPropertiesForType() skips every property with JsonIgnoreAttribute, so this conditional attribute excludes configSource.optOut from aspire config info --json. The extension's schema generator disallows additional properties on typed objects, causing the opt-out configuration written here to fail validation even after schema regeneration. Preserve the serialization suppression, but make the schema builder skip only unconditional ignores and add a regression assertion for configSource.optOut.

2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The schema builder omits conditionally ignored optOut from the generated configuration schema, causing VS Code to flag opt-out files produced by this change as invalid.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Include conditionally ignored properties in generated config schema

src/​Aspire.Cli/​Configuration/​ConfigSource.cs:16

SettingsSchemaBuilder.BuildPropertiesForType skips every property carrying JsonIgnoreAttribute, regardless of its condition. This therefore omits optOut from aspire config info --json; extension/scripts/generate-schema.js uses that output to generate a configSource schema with additionalProperties: false, so VS Code flags the opt-out files produced by this PR as invalid. Update the schema builder to exclude only unconditionally ignored properties and add a regression assertion that configSource.optOut is present.

Review effort: Balanced

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@mitchdenny Mitch Denny (mitchdenny) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking naming question: are we sticking with optOut, rather than disabled or enabled? optOut captures the explicit decision not to adopt a source, whereas enabled/disabled might suggest toggling an existing binding. Happy to keep optOut; this is not a blocker. Approving.

@JamesNK
James Newton-King (JamesNK) merged commit 7961070 into main Nov 2, 2026
418 of 421 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Nov 2, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #2024

Generated by PR Documentation Check · copilot · auto · 25.9 AIC · ⌖ 1.15 AIC · ⊞ 7.1K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#2024 targeting release/17.0.

Updated aspire-update.mdx to document config source adoption, the --use-config-source option, and project opt-out. Signals: cli_command_file_changed (UpdateCommand.cs), pr_body_has_cli_flag_mention (--use-config-source), pr_body_has_user_facing_section ("User-facing usage"). Please confirm that --config-source (refresh-only), mentioned in the PR body, is documented elsewhere.

Note

This draft PR needs human review before merging.

James Newton-King (JamesNK) added a commit that referenced this pull request Nov 2, 2026
## Description

Existing AppHosts do not currently tell users when an organization
configuration source is available but has not been adopted. `aspire
doctor` now reports machine source availability and the current
AppHost's saved configuration-source choice, with a non-blocking
suggestion to run `aspire update` when no choice has been recorded.

**PR stack:** `main` -> #21678 (brownfield adoption) -> this doctor PR.

**Stacked PR:** depends on #21678 and targets
[`jamesnk/config-source-brownfield`](https://github.com/microsoft/aspire/tree/jamesnk/config-source-brownfield),
which contains brownfield adoption and persisted `configSource.optOut`
support. This PR adds only the doctor diagnostics and their supporting
discovery extraction, tests, localization, and documentation.

- Report environment-variable and Microsoft-employee source candidates,
including their discovery origin.
- Report an AppHost's saved binding or explicit opt-out without
suggesting adoption.
- Include stable diagnostic names and metadata in JSON output.
- Reuse doctor's shallow AppHost discovery and extract candidate
resolution without consent prompts, Git acquisition, remote-version
checks, or configuration writes.

Project diagnostics currently inspect the nearest local configuration.
Reporting and accounting for saved global source bindings remains
follow-up work; a project using global defaults can still receive the
local-adoption warning.

### User-facing usage

```shell
aspire doctor
aspire doctor --format json
```

Relevant existing command help, also exercised by the doctor tests:

```text
Usage:
  aspire doctor [options]

Options:
  --format <Json|Table>  Output format (Table or Json)
```

When a candidate is available and the AppHost has no recorded choice,
doctor reports a warning with:

```text
Run 'aspire update' to choose whether this AppHost should use the available configuration source.
```

JSON output includes the `config-source` environment check and, when
applicable, the `apphost-config-source` check with a `bound`,
`optedOut`, or `unconfigured` state. An explicit opt-out is reported as
an intentional choice, not something to fix.

### Screenshots / Recordings

> **This PR includes UI changes.** Please add screenshots or screen
recordings so reviewers can evaluate the visual changes without running
locally.
>
> - For before/after comparisons, place them side-by-side or label them
clearly.
> - For interactive changes (animations, transitions, new flows), prefer
a short screen recording (GIF or video).
> - If you cannot capture visuals now, note what scenario to test and
mark this section as TODO.

TODO: Capture `aspire doctor` with `ASPIRE_INIT_SOURCE_URL` set in an
AppHost with no saved source choice, showing availability, the adoption
warning, and its suggested fix. Also capture saved-binding and
explicit-opt-out states. No visual capture was made during this change.

<!-- Add screenshots/recordings here -->

### Validation

Focused validation rerun after splitting the branches: **passed, 52
succeeded, 0 failed, 0 skipped**.

```powershell
$env:MSBUILDTERMINALLOGGER='false'
dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ConfigSourceCheckTests" --filter-class "*.DoctorCommandTests" --filter-class "*.EnvironmentCheckerTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

Broader doctor, creation, and config-source regression coverage, run
before splitting the same implementation into commits: **passed, 784
succeeded, 0 failed, 2 skipped**.

```powershell
$env:MSBUILDTERMINALLOGGER='false'
dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ConfigSourceCheckTests" --filter-class "*.DoctorCommandTests" --filter-class "*.EnvironmentCheckerTests" --filter-class "*.ConfigSourceServiceTests" --filter-class "*.ConfigSourceCommandTests" --filter-class "*.NewCommandLocalTemplateTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
```

Localization regeneration: **passed, 0 warnings and 0 errors**.

```powershell
dotnet build src\Aspire.Cli\Aspire.Cli.csproj /t:UpdateXlf
```

Doctor-only diff whitespace validation: **passed**.

```powershell
git diff --check jamesnk/config-source-brownfield...jamesnk/doctor-config-sources
```

The full repository suite and manual visual verification were not run.

Fixes # (issue)

## Checklist

- Is this feature complete?
  - [ ] Yes. Ready to ship.
  - [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] 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
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [ ] Yes
    - If yes, have you done a threat model and had a security review?
      - [ ] Yes
      - [ ] No
  - [x] No

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants