From b5bac44c526a4f26ab8683e103802c95bfc737be Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 10 Nov 2026 14:59:36 +0800 Subject: [PATCH 01/14] docs: document configuration sources and CLI options Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/config/sidebar/docs.topics.ts | 4 + .../docs/extensibility/config-sources.mdx | 276 ++++++++++++++++++ .../reference/cli/commands/aspire-init.mdx | 12 + .../reference/cli/commands/aspire-new.mdx | 19 +- .../reference/cli/commands/aspire-update.mdx | 32 +- .../docs/reference/cli/configuration.mdx | 4 + 6 files changed, 341 insertions(+), 6 deletions(-) create mode 100644 src/frontend/src/content/docs/extensibility/config-sources.mdx diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index 5085b76fa6..a83ba33498 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -1124,6 +1124,10 @@ export const docsTopics = { ja: '拡張性', }, items: [ + { + label: 'Configuration sources', + slug: 'extensibility/config-sources', + }, { label: 'Custom resources', slug: 'extensibility/custom-resources', diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx new file mode 100644 index 0000000000..e37525156f --- /dev/null +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -0,0 +1,276 @@ +--- +title: Configuration sources +description: Learn how to use a configuration source and create, secure, and distribute organization-specific Aspire defaults. +--- + +Configuration sources let an organization share Aspire defaults from a Git-hosted +`aspire.config.json`. Use them to offer custom agent skills, integration feeds, +and project templates without maintaining a separate Aspire CLI distribution. + +These are optional defaults, not enforced policy. Developers can decline a source +or edit the resulting app configuration. + +- [Use a configuration source](#use-a-configuration-source) to accept or decline + shared defaults, understand what they control, and manage updates. +- [Create a configuration source](#create-a-configuration-source) to publish + defaults, secure their content, and distribute settings to developers. + +All repositories, feeds, documentation URLs, and commit IDs in these examples are +illustrative. Replace them with your organization's locations and reviewed full +commit IDs before running the commands. + +## Use a configuration source + +### Decide what to trust + +:::caution[Only use sources you trust] +Content selected by a configuration source can run code on your machine or +influence an agent's actions. Only accept publishers and content suppliers you +trust. Run Aspire commands only from trusted directories and repositories, even +when you select an AppHost in another directory. See the +[Aspire CLI overview](/reference/cli/overview/). +::: + +Before accepting, check who owns the configuration repository and read the linked +source documentation. Review the skill repositories, feeds, catalogs, and +templates it selects: trusting the configuration publisher also means trusting +those suppliers. + +### Opt in or out + +Install the [Aspire CLI](/get-started/install-cli/) and Git. Aspire fetches +configuration sources using your existing Git credentials. + +Your organization can [configure a source](#configure-the-source-settings) in +your environment. When you run `aspire new` or `aspire init`, the CLI displays +source details, a documentation link if provided, and a trust warning before +asking whether to use it. Accept to apply the shared defaults, or decline to +continue with standard Aspire defaults and record an app-local opt-out. + +To opt out of an existing app's source, replace only the `configSource` property +in the app's `aspire.config.json` with: + +```json title="App configuration excerpt" +{ + "configSource": { + "optOut": true + } +} +``` + +This stops configuration-source update checks and refreshes. It doesn't remove +previously applied settings, uninstall plugins, remove persisted NuGet mappings, +or undo generated code. + +To opt in for an existing app that has no `configSource` property, run +`aspire update --use-config-source`. This command also performs normal project +updates. If the app has an opt-out, remove that `configSource` property first, +leaving other settings intact. + +### Understand what the source controls + +| Section | Purpose | +| -------------------- | ------------------------------------------------------------------------ | +| `skillSources` | Agent marketplace/plugin repositories and optional OpenCode catalogs | +| `integrationSources` | NuGet feeds or local package directories searched for integrations | +| `templateSources` | Git repositories or local directories used to discover project templates | + +The CLI persists `skillSources` and `integrationSources` in the app's local +configuration. Template sources are available during app creation but aren't +copied into the generated app. Unrelated settings in the shared file aren't +imported. + +Skill initialization registers sources in the selected agent's native settings; +the agent acquires the content. Integration selection can add a package and +persist its feed mapping. Template selection generates an app. Applying the +configuration alone doesn't install every referenced item. + +Built-in skill and integration sources remain enabled unless you explicitly +disable or override their `default` entries. Normal global/local consumer +configuration precedence still applies; configuration sources aren't an +administrative allowlist. + +### Understand the saved binding + +After acceptance, the app's `aspire.config.json` contains the applied skill and +integration settings and a binding like this: + +```json title="App configuration excerpt" +{ + "configSource": { + "repository": "https://github.com/contoso/aspire-config.git", + "path": "teams/platform/aspire.config.json", + "ref": "0123456789abcdef0123456789abcdef01234567", + "appliedVersion": "abcdef0123456789abcdef0123456789abcdef01" + } +} +``` + +`ref` selects a configuration branch or **commit**. `appliedVersion` identifies the +configuration file's Git **blob** last applied to the app. It is an update-tracking +value, not a pin, signature, or approval record. Git object IDs have 40 characters +for SHA-1 repositories or 64 for SHA-256 repositories. + +The binding is app-local. Configuration sources don't support global bindings or +refresh global configuration. Changing initialization environment variables +doesn't retarget an existing binding, and cloning the app brings its saved +configuration with it without repeating the original acceptance prompt. + +### Update the app's configuration + +Project commands can report that configuration has changed, but they don't apply +new defaults automatically. To refresh the selected app's saved configuration: + +```powershell +aspire update --config-source +``` + +For a branch/default-branch binding, this applies the currently published +configuration. For a full-commit binding, it reads the same pinned commit. To +advance a pin, review the new commit and change the app's `configSource.ref` +before running the refresh command. Keep unrelated app settings, and let the CLI +record the new `appliedVersion`; don't substitute a commit ID for that blob ID. + +A supplied persisted section replaces the corresponding local section, including +local edits and entries omitted by the publisher. An omitted section leaves +existing values unchanged. Review the app diff before committing it. + +Refresh doesn't update the CLI or SDK, regenerate an app, install integration +packages, or reconcile existing agent registrations. Existing native agent pins +are preserved; changing Aspire settings doesn't silently retarget an existing +registration. Advance downstream refs through reviewed configuration changes, +then use the corresponding consumer workflow to acquire the intended content. + +## Create a configuration source + +### Host the configuration on Git + +Create a Git repository and check in an `aspire.config.json`. You can place it at +the repository root or in a subdirectory and select its path through the +[source settings](#configure-the-source-settings). + +Repository addresses can use HTTPS, SSH URLs, or SCP-style SSH syntax. Absolute +local Git repository paths are also supported, but saved paths are +machine-specific. Relative repository paths and `file://` URLs aren't supported. +Use a repository that your developers can access with their existing Git +credentials. Keep credentials out of repository URLs and configuration files. + +Include the `skillSources`, `integrationSources`, and `templateSources` sections +you want to supply. For example: + +```json title="aspire.config.json in the configuration repository" +{ + "skillSources": { + "contoso": { + "repository": "https://github.com/contoso/aspire-skills.git", + "ref": "89abcdef0123456789abcdef0123456789abcdef", + "marketplace": "contoso", + "plugins": ["aspire"] + } + }, + "integrationSources": { + "contoso": { + "source": "https://packages.contoso.com/nuget/v3/index.json", + "patterns": ["Contoso.Hosting.*"] + } + }, + "templateSources": { + "contoso": { + "repository": "https://github.com/contoso/aspire-templates.git", + "ref": "fedcba9876543210fedcba9876543210fedcba98", + "path": "templates" + } + } +} +``` + +Don't declare a `configSource` inside the shared file. The CLI creates that +binding in the app; recursive configuration sources aren't supported. Keep the +file reasonably sized and avoid unnecessarily broad feed patterns. Package +patterns limit discovery, not publisher trust. Different names for the same +integration feed combine their patterns by union. + +### Secure publication + +Treat write access to configuration and downstream content repositories as +code-publication authority. Protect the publication branch with required reviews +and checks, restrict who can push or merge, and control administrative bypasses. +Review access for both people and automation identities. Prevent unreviewed +force-pushes or branch deletion, and keep pinned commits available for Git +acquisition. + +Apply these controls to the skill, template, and catalog repositories as well as +the configuration repository. Use approved HTTPS feeds/catalogs or trusted SSH +transport, and keep credentials and other secrets out of published content. + +### Pin each part of the supply chain + +A trusted repository can still receive an unintended change or be compromised. +Pinning to an approved full commit ID prevents a later branch update from +silently selecting different Git content. A branch name, tag, or omitted ref isn't +an immutable content pin. For configuration-source and skill-source selectors, +use a branch or full commit ID rather than an abbreviated hash or tag. + +Pin each layer independently: + +- **Skill marketplaces**: Set each `skillSources..ref` to an approved full + commit ID. +- **Templates**: Set each Git-backed `templateSources..ref` to an approved + full commit ID. +- **Integration packages**: A feed URL or package-ID pattern isn't a content pin. + Review selected package versions and use your organization's NuGet source, + restore, and package-integrity controls. + +### Provide a README + +Publish a README or documentation page that helps developers decide whether to +accept the source. Explain: + +- Who owns the source and how to contact them. +- Which skills, feeds, templates, and other suppliers it references. +- What accepting the source changes, and how to opt out or update. +- Which Git credentials and repository permissions developers need. +- How commits are reviewed, pinned, and approved for distribution. +- How to recover from compromised content that has already been acquired. + +Set `ASPIRE_INIT_SOURCE_README_URL` to the page's absolute HTTPS URL so the CLI +shows a documentation link before acceptance. + +### Configure the source settings + +To select a custom source, set `ASPIRE_INIT_SOURCE_URL` in the developer's +environment. The other settings are optional: + +| Variable | Purpose | Default | +| ------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- | +| `ASPIRE_INIT_SOURCE_URL` | Git repository URL or absolute local Git repository path, not a raw JSON URL | No source, except for detected Microsoft employees | +| `ASPIRE_INIT_SOURCE_PATH` | Optional repository-relative configuration file path, using `/` separators | `aspire.config.json` | +| `ASPIRE_INIT_SOURCE_REF` | Optional branch name or full commit ID | The repository's current default branch | +| `ASPIRE_INIT_SOURCE_README_URL` | Optional HTTP or HTTPS documentation link shown before acceptance | No link, except for the Microsoft source | + +An explicit `ASPIRE_INIT_SOURCE_URL` takes precedence over employee detection. +Path and ref overrides apply only when the URL is explicitly set. + +Test the settings in a PowerShell session before distributing them: + +```powershell +$env:ASPIRE_INIT_SOURCE_URL = 'https://github.com/contoso/aspire-config.git' +$env:ASPIRE_INIT_SOURCE_PATH = 'teams/platform/aspire.config.json' +$env:ASPIRE_INIT_SOURCE_REF = '0123456789abcdef0123456789abcdef01234567' +$env:ASPIRE_INIT_SOURCE_README_URL = 'https://engineering.contoso.com/aspire' +aspire new +``` + +An explicitly configured initialization-source URL can also provide a runtime-only +template discovery overlay without saving those definitions globally or into an +app. Employee detection alone doesn't enable that overlay. + +### Distribute settings across your organization + +Set the variables through your existing device-management or developer-onboarding +tools: Group Policy or Intune on Windows, Jamf on macOS, Ansible on Linux, or +shared setup scripts and shell profiles across platforms. Ensure new terminal +and IDE sessions inherit the settings. + +This makes the source available; it doesn't accept it for developers or change +existing app bindings. diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx index ab7dd40f40..83d649fd8f 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx @@ -129,6 +129,12 @@ The following options are available: Create `apphost.cs` in the current directory, skipping .NET solution discovery. Requires C#: fails with an error if another language is selected explicitly, via configuration, or at the language prompt. +- **`--use-config-source [true|false]`** + + Choose whether to apply an offered [configuration source](/extensibility/config-sources/) when initializing the app. Pass `--use-config-source` or `--use-config-source true` to accept, or `--use-config-source false` to decline and save an app-local opt-out. + + If a source is available, interactive initialization prompts when this option is omitted; non-interactive initialization requires an explicit choice. Requesting acceptance when no source is available is an error. An existing app-local source binding or opt-out is preserved. + - **`--agents `** Comma-separated agent IDs: `copilot`, `claude`, or `opencode`. Use `all` to configure all supported agents or `none` to skip agent configuration. For selection defaults, see the [`aspire agent init` command reference](../aspire-agent-init/#options). @@ -185,6 +191,12 @@ The following options are available: aspire init --non-interactive --agents none ``` +- Initialize Aspire support non-interactively and decline an available configuration source: + + ```bash title="Aspire CLI" + aspire init --language csharp --agents none --use-config-source false --non-interactive + ``` + - Initialize Aspire support and enable skill sources for GitHub Copilot without prompts: ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index 45229351b9..76170c5e11 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -38,10 +38,11 @@ The `--output` option validates the provided path before creating the project: - Paths that point to an **existing non-empty directory** are rejected with a clear error message. Use a different output path or an empty directory. ## Interactive prompts @@ -165,7 +166,9 @@ The following options are available: - **`--use-config-source [true|false]`** - Accept a Git configuration source that's available for the project, or pass `false` to use standard Aspire configuration instead. Specify this option to respond to the configuration source prompt in non-interactive mode. + Choose whether to use the offered [configuration source](/extensibility/config-sources/) during project creation. Pass `--use-config-source` or `--use-config-source true` to accept, or `--use-config-source false` to decline and save an app-local opt-out. + + If a source is available and this option is omitted, the CLI asks for consent interactively. Non-interactive creation requires an explicit choice. Requesting acceptance when no source is available is an error. - **`--suppress-agent-init`** @@ -260,6 +263,12 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f aspire new aspire-starter --name myapp --agents none --non-interactive ``` +- Create a new project non-interactively and accept an available configuration source: + + ```bash title="Aspire CLI" + aspire new aspire-starter --name myapp --agents none --use-config-source --non-interactive + ``` + - Create a new project non-interactively and configure all supported agents at the project scope: ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx index ae3f8e7689..ebcc56d2f1 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx @@ -46,6 +46,12 @@ If you specify `--non-interactive` without `--yes`, the command exits with an er The update command requires --yes when the --non-interactive option is specified. ``` +`--yes` doesn't consent to adopting a configuration source. By default, a normal +non-interactive update doesn't adopt a source for an app that has no binding. To +accept an available source as part of the update, also pass +`--use-config-source`. To explicitly decline, pass `--use-config-source false`. +Existing source bindings and opt-outs aren't changed by this option. + ### Updating repository Aspire CLI references A repository can pin the Aspire CLI independently of the executable you're currently running, using an `Aspire.Cli` entry in `.config/dotnet-tools.json` or `dotnet-tools.json`, or an `@microsoft/aspire-cli` entry in `package.json` (`dependencies`, `devDependencies`, or `optionalDependencies`). `aspire update` updates these existing pins alongside AppHost integrations, or without an AppHost. @@ -104,6 +110,18 @@ The following options are available: Update the Aspire CLI itself to the latest version. The CLI adapts to how it was installed: npm and .NET tool installs print the matching package-manager command to run, while install-script and other binary installs download the latest binary directly. See [Updating the CLI based on how it was installed](#updating-the-cli-based-on-how-it-was-installed). +- **`--config-source`** + + Refresh only the saved app-local [configuration source](/extensibility/config-sources/) and apply its shared settings. This doesn't adopt a new source, update packages, update the SDK or CLI, regenerate templates, or reconcile existing agent registrations. If there is no active saved binding, the command reports that no source is bound and leaves the configuration unchanged. + + Can't be combined with `--self`, `--migrate`, `--channel`, `--quality`, or `--nuget-config-dir`. Non-interactive refresh also requires `--yes`. + +- **`--use-config-source [true|false]`** + + Choose whether to adopt an offered configuration source during a normal project update when the app has no source binding or saved opt-out. Pass `--use-config-source` or `--use-config-source true` to accept, or `--use-config-source false` to decline and save an app-local opt-out. Requesting acceptance when no source is available is an error. + + When omitted, interactive updates can ask for consent; non-interactive updates skip adoption. Existing bindings and opt-outs are preserved. Use `--config-source` instead to refresh an existing binding without updating packages. + - **`--channel`** Channel to update to (`stable`, `staging`, `daily`). When switching channels, `aspire update` applies all package version edits to your project first and then runs a single `dotnet restore`, ensuring that NuGet source mappings added for the target channel are in place before any restore is attempted. @@ -124,7 +142,7 @@ The following options are available: - **`-y, --yes`** - Automatically confirm all prompts without user input. Use this option in CI/CD pipelines or other non-interactive environments to skip confirmation dialogs. + Automatically confirm update prompts without user input. Use this option in CI/CD pipelines or other non-interactive environments to skip confirmation dialogs. This doesn't accept a new configuration source; use `--use-config-source` for that choice. - **`--nuget-config-dir`** @@ -162,6 +180,18 @@ The following options are available: aspire update --yes --non-interactive ``` +- Update packages non-interactively and accept an available configuration source for an app without a binding or opt-out: + + ```bash title="Aspire CLI" + aspire update --use-config-source --yes --non-interactive + ``` + +- Refresh only the app's saved configuration source without interactive prompts: + + ```bash title="Aspire CLI" + aspire update --config-source --yes --non-interactive + ``` + - Update packages using a specific NuGet configuration file: ```bash title="Aspire CLI" diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx index 291d3e964f..15a090024b 100644 --- a/src/frontend/src/content/docs/reference/cli/configuration.mdx +++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx @@ -12,6 +12,10 @@ project-scoped CLI configuration. Use the `aspire config` command family to inspect and update those settings, and use `aspire config list --all` to see the feature flags surfaced by your installed CLI. +To share organization-specific skill, integration, and template defaults through +Git, see [Configuration sources](/extensibility/config-sources/), including +examples for pinning configuration and downstream content to approved commits. + ## Configuration file model From 5715de840b3d015d3f22069efed408d8289f72a1 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 10 Nov 2026 15:13:56 +0800 Subject: [PATCH 02/14] docs: proofread configuration sources Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/extensibility/config-sources.mdx | 82 +++++++++---------- 1 file changed, 39 insertions(+), 43 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index e37525156f..7599865d70 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -3,18 +3,14 @@ title: Configuration sources description: Learn how to use a configuration source and create, secure, and distribute organization-specific Aspire defaults. --- -Configuration sources let an organization share Aspire defaults from a Git-hosted -`aspire.config.json`. Use them to offer custom agent skills, integration feeds, -and project templates without maintaining a separate Aspire CLI distribution. +Aspire configuration sources provide organization-specific developer defaults +through a Git-hosted `aspire.config.json` file. Use a configuration source to +share custom agent skills, integration feeds, and project templates tailored to +your organization's needs. These are optional defaults, not enforced policy. Developers can decline a source or edit the resulting app configuration. -- [Use a configuration source](#use-a-configuration-source) to accept or decline - shared defaults, understand what they control, and manage updates. -- [Create a configuration source](#create-a-configuration-source) to publish - defaults, secure their content, and distribute settings to developers. - All repositories, feeds, documentation URLs, and commit IDs in these examples are illustrative. Replace them with your organization's locations and reviewed full commit IDs before running the commands. @@ -31,10 +27,9 @@ when you select an AppHost in another directory. See the [Aspire CLI overview](/reference/cli/overview/). ::: -Before accepting, check who owns the configuration repository and read the linked -source documentation. Review the skill repositories, feeds, catalogs, and -templates it selects: trusting the configuration publisher also means trusting -those suppliers. +Before accepting, review the configuration repository, its linked documentation, +and every skill, feed, catalog, and template it references. Trusting the +publisher also means trusting those suppliers. ### Opt in or out @@ -107,9 +102,8 @@ integration settings and a binding like this: ``` `ref` selects a configuration branch or **commit**. `appliedVersion` identifies the -configuration file's Git **blob** last applied to the app. It is an update-tracking -value, not a pin, signature, or approval record. Git object IDs have 40 characters -for SHA-1 repositories or 64 for SHA-256 repositories. +Git **blob** for the configuration file last applied to the app. It tracks updates; +it isn't a pin, signature, or approval record. The binding is app-local. Configuration sources don't support global bindings or refresh global configuration. Changing initialization environment variables @@ -125,21 +119,23 @@ new defaults automatically. To refresh the selected app's saved configuration: aspire update --config-source ``` -For a branch/default-branch binding, this applies the currently published -configuration. For a full-commit binding, it reads the same pinned commit. To -advance a pin, review the new commit and change the app's `configSource.ref` -before running the refresh command. Keep unrelated app settings, and let the CLI -record the new `appliedVersion`; don't substitute a commit ID for that blob ID. +If the source is bound to a branch or uses the repository's default branch, this +applies the current configuration. If it's bound to a full commit, the CLI reads +that pinned commit. To advance a pin, review the new commit and change the app's +`configSource.ref` before refreshing. Keep unrelated app settings, and let the CLI +record the new `appliedVersion`; don't substitute a commit ID for the blob ID. -A supplied persisted section replaces the corresponding local section, including -local edits and entries omitted by the publisher. An omitted section leaves -existing values unchanged. Review the app diff before committing it. +If the source supplies a `skillSources` or `integrationSources` section, it +replaces the corresponding section in the app's local configuration, including +local edits and entries the source omits. If the source omits a section entirely, +the app's existing values remain unchanged. Review the app diff before committing +it. Refresh doesn't update the CLI or SDK, regenerate an app, install integration -packages, or reconcile existing agent registrations. Existing native agent pins -are preserved; changing Aspire settings doesn't silently retarget an existing -registration. Advance downstream refs through reviewed configuration changes, -then use the corresponding consumer workflow to acquire the intended content. +packages, or update existing agent registrations. Changing Aspire settings +doesn't retarget an existing registration or change its native pins. To acquire +updated content, update the refs in a reviewed configuration change, then use +the relevant consumer's workflow. ## Create a configuration source @@ -186,18 +182,17 @@ you want to supply. For example: Don't declare a `configSource` inside the shared file. The CLI creates that binding in the app; recursive configuration sources aren't supported. Keep the -file reasonably sized and avoid unnecessarily broad feed patterns. Package -patterns limit discovery, not publisher trust. Different names for the same -integration feed combine their patterns by union. +file focused and use narrow feed patterns. Package patterns limit discovery, not +publisher trust. Patterns are combined when the same feed is configured under +different names. ### Secure publication -Treat write access to configuration and downstream content repositories as -code-publication authority. Protect the publication branch with required reviews +Treat write access to the configuration and referenced content repositories as +permission to publish code. Protect publication branches with required reviews and checks, restrict who can push or merge, and control administrative bypasses. -Review access for both people and automation identities. Prevent unreviewed -force-pushes or branch deletion, and keep pinned commits available for Git -acquisition. +Review access for people and automation identities. Prevent unreviewed force +pushes or branch deletion, and keep pinned commits available for Git acquisition. Apply these controls to the skill, template, and catalog repositories as well as the configuration repository. Use approved HTTPS feeds/catalogs or trusted SSH @@ -227,14 +222,15 @@ Publish a README or documentation page that helps developers decide whether to accept the source. Explain: - Who owns the source and how to contact them. -- Which skills, feeds, templates, and other suppliers it references. -- What accepting the source changes, and how to opt out or update. -- Which Git credentials and repository permissions developers need. -- How commits are reviewed, pinned, and approved for distribution. -- How to recover from compromised content that has already been acquired. - -Set `ASPIRE_INIT_SOURCE_README_URL` to the page's absolute HTTPS URL so the CLI -shows a documentation link before acceptance. +- Which skills, feeds, templates, and suppliers it references, and what accepting + the source changes. +- How developers can opt out or update, and which Git credentials and + repository permissions they need. +- How commits are reviewed, pinned, and approved, and how to recover from + compromised content. + +Set `ASPIRE_INIT_SOURCE_README_URL` to the page's absolute URL so the CLI shows a +documentation link before acceptance. Use HTTPS for a secure connection. ### Configure the source settings From bacdb5cb9737d8281543f4dfedc8153796436e7b Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 10 Nov 2026 15:20:37 +0800 Subject: [PATCH 03/14] docs: move configuration sources in sidebar Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/config/sidebar/docs.topics.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index a83ba33498..d7741f9475 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -1124,10 +1124,6 @@ export const docsTopics = { ja: '拡張性', }, items: [ - { - label: 'Configuration sources', - slug: 'extensibility/config-sources', - }, { label: 'Custom resources', slug: 'extensibility/custom-resources', @@ -1173,6 +1169,10 @@ export const docsTopics = { slug: 'extensibility/typescript-hosting-integrations', badge: 'Experimental', }, + { + label: 'Configuration sources', + slug: 'extensibility/config-sources', + }, ], }, { From c633fb399a4288d81e2455d125b6a7d2ef794fb4 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 14:59:19 +0800 Subject: [PATCH 04/14] docs: clarify configuration source CLI behavior Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../docs/extensibility/config-sources.mdx | 34 +++++++++++++++++-- .../reference/cli/commands/aspire-add.mdx | 4 +++ .../reference/cli/commands/aspire-init.mdx | 4 +++ .../reference/cli/commands/aspire-new.mdx | 32 +++++++++++++++++ .../reference/cli/commands/aspire-update.mdx | 6 +++- 5 files changed, 76 insertions(+), 4 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index 7599865d70..42339e8f3f 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -3,6 +3,8 @@ title: Configuration sources description: Learn how to use a configuration source and create, secure, and distribute organization-specific Aspire defaults. --- +import OsAwareTabs from '@components/OsAwareTabs.astro'; + Aspire configuration sources provide organization-specific developer defaults through a Git-hosted `aspire.config.json` file. Use a configuration source to share custom agent skills, integration feeds, and project templates tailored to @@ -17,6 +19,8 @@ commit IDs before running the commands. ## Use a configuration source +Review the source and its referenced content before accepting its defaults. + ### Decide what to trust :::caution[Only use sources you trust] @@ -27,6 +31,10 @@ when you select an AppHost in another directory. See the [Aspire CLI overview](/reference/cli/overview/). ::: +The CLI displays the warning "Only use sources you trust. Content from these +sources can run code on your machine." when it offers or fetches a configuration +source. `--use-config-source` and `--yes` don't suppress this warning. + Before accepting, review the configuration repository, its linked documentation, and every skill, feed, catalog, and template it references. Trusting the publisher also means trusting those suppliers. @@ -115,7 +123,7 @@ configuration with it without repeating the original acceptance prompt. Project commands can report that configuration has changed, but they don't apply new defaults automatically. To refresh the selected app's saved configuration: -```powershell +```bash title="Refresh the saved configuration source" aspire update --config-source ``` @@ -139,6 +147,9 @@ the relevant consumer's workflow. ## Create a configuration source +Create and publish a Git-hosted configuration file, then make its location +available to developers. + ### Host the configuration on Git Create a Git repository and check in an `aspire.config.json`. You can place it at @@ -247,9 +258,23 @@ environment. The other settings are optional: An explicit `ASPIRE_INIT_SOURCE_URL` takes precedence over employee detection. Path and ref overrides apply only when the URL is explicitly set. -Test the settings in a PowerShell session before distributing them: +Test the settings in a terminal session before distributing them: + + +
-```powershell +```bash title="Configure and use a source" +export ASPIRE_INIT_SOURCE_URL='https://github.com/contoso/aspire-config.git' +export ASPIRE_INIT_SOURCE_PATH='teams/platform/aspire.config.json' +export ASPIRE_INIT_SOURCE_REF='0123456789abcdef0123456789abcdef01234567' +export ASPIRE_INIT_SOURCE_README_URL='https://engineering.contoso.com/aspire' +aspire new +``` + +
+
+ +```powershell title="Configure and use a source" $env:ASPIRE_INIT_SOURCE_URL = 'https://github.com/contoso/aspire-config.git' $env:ASPIRE_INIT_SOURCE_PATH = 'teams/platform/aspire.config.json' $env:ASPIRE_INIT_SOURCE_REF = '0123456789abcdef0123456789abcdef01234567' @@ -257,6 +282,9 @@ $env:ASPIRE_INIT_SOURCE_README_URL = 'https://engineering.contoso.com/aspire' aspire new ``` +
+
+ An explicitly configured initialization-source URL can also provide a runtime-only template discovery overlay without saving those definitions globally or into an app. Employee detection alone doesn't enable that overlay. diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx index 7e88434bd7..327c8aa521 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx @@ -40,6 +40,10 @@ The following arguments are available: If a partial name or invalid name is provided, the CLI searches NuGet for approximate matches and prints them in the terminal for the user to select. If no results are found, all packages are listed. +:::caution[Only use sources you trust] +Content from package sources can run code on your machine. The CLI displays a trust warning when you specify a source other than nuget.org or discover packages from such a source. +::: + ## Options The following options are available: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx index 83d649fd8f..29355da6fa 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx @@ -117,6 +117,10 @@ The skill instructs the agent to: - Optionally configure OpenTelemetry - Validate the wiring with a smoke-test `aspire start` +:::caution[Only use sources you trust] +Content selected by a configuration source can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a source, even if you pass `--use-config-source`. Review the source and its referenced content before accepting it. See [Configuration sources](/extensibility/config-sources/). +::: + ## Options The following options are available: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index 76170c5e11..ee634b6371 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -118,6 +118,10 @@ aspire certs trust Choosing **No** (the default) configures services with standard `http://localhost:` addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration. +:::caution[Only use sources you trust] +Content from configuration sources, template repositories, and package sources can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a configuration source, fetches a Git template repository, or uses a package source other than nuget.org. Passing `--use-config-source` doesn't suppress the warning. Review sources and their referenced content before using them. See [Configuration sources](/extensibility/config-sources/). +::: + ## Options The following options are available: @@ -138,6 +142,20 @@ The following options are available: The version of the project templates to use. +- **`--template-path `** + + Path to an unpacked template package directory. With `--template-repository`, the path is relative to the repository root. + +- **`--template-repository `** + + Git repository containing templates. The CLI fetches the repository and discovers templates at its root unless you also specify `--template-path`. + +- **`--template-repository-ref `** + + Branch, tag, or full commit ID for the template repository. Requires `--template-repository`; defaults to the repository's HEAD. + + `--template-path` and `--template-repository` can't be combined with a template subcommand, `--source`, `--version`, `--channel`, or `--language`. If the source contains multiple templates, select one interactively. + - **`--channel`** Channel to use for templates (`stable`, `staging`, `daily`). If you don't specify `--version`, `aspire new` selects a template package from the channel and prefers the version that matches the currently installed CLI/SDK. For explicit pre-release channels, such as `staging` and `daily`, it pins templates to the installed CLI/SDK version when the feed would otherwise select a newer pre-release package. For example, a `13.4` CLI using `--channel daily` won't pull `13.5` preview templates even if the daily feed contains them. If you specify `--version`, that template version is used with the selected channel. @@ -237,6 +255,20 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f aspire new aspire-go-starter --non-interactive --use-redis-cache true ``` +## Template sources + +Use `aspire template source list` to list named template sources without discovering templates. It combines global template sources with sources from an accepted configuration source for that invocation. It doesn't save the inherited sources globally or in an app. + +For JSON output, the command lists global sources without consulting a configuration source by default. Pass `--use-config-source` to accept the offered source and include its template sources: + +```bash title="List template sources as JSON" +aspire template source list --format json --use-config-source +``` + +In table output, the command offers an available source interactively. Pass `--use-config-source false` to decline it. The CLI displays a trust warning even when `--use-config-source` supplies the choice. + +The CLI also displays a trust warning when you register a template source with `aspire template source add`; passing `--yes` skips confirmation but doesn't suppress the warning. + ## Examples - Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx index ebcc56d2f1..16326fefdc 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx @@ -100,6 +100,10 @@ If your repository doesn't pin the CLI, you can run `aspire update --self` befor Run `nix profile upgrade aspire-cli` for a profile install, or `nix flake update ` for a project flake. +:::caution[Only use sources you trust] +Content selected by a configuration source can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a source during an update or fetches a saved source with `--config-source`. Neither `--yes` nor `--use-config-source` suppresses the warning. Review the source and its referenced content before accepting or refreshing it. See [Configuration sources](/extensibility/config-sources/). +::: + ## Options The following options are available: @@ -112,7 +116,7 @@ The following options are available: - **`--config-source`** - Refresh only the saved app-local [configuration source](/extensibility/config-sources/) and apply its shared settings. This doesn't adopt a new source, update packages, update the SDK or CLI, regenerate templates, or reconcile existing agent registrations. If there is no active saved binding, the command reports that no source is bound and leaves the configuration unchanged. + Refresh only the nearest saved app-local [configuration source](/extensibility/config-sources/) and apply its shared settings. Supplied skill and integration sections replace the corresponding local sections, including local edits. This doesn't adopt a new source, update packages, update the SDK or CLI, regenerate templates, or reconcile existing agent registrations. If there is no active saved binding, the command reports that no source is bound and leaves the configuration unchanged. Can't be combined with `--self`, `--migrate`, `--channel`, `--quality`, or `--nuget-config-dir`. Non-interactive refresh also requires `--yes`. From d6696eb7a319bd29e4c6aded56e0c692b37d7e70 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:06:28 +0800 Subject: [PATCH 05/14] docs: limit CLI reference changes to config sources Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../reference/cli/commands/aspire-add.mdx | 4 --- .../reference/cli/commands/aspire-new.mdx | 29 ++++--------------- 2 files changed, 6 insertions(+), 27 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx index 327c8aa521..7e88434bd7 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx @@ -40,10 +40,6 @@ The following arguments are available: If a partial name or invalid name is provided, the CLI searches NuGet for approximate matches and prints them in the terminal for the user to select. If no results are found, all packages are listed. -:::caution[Only use sources you trust] -Content from package sources can run code on your machine. The CLI displays a trust warning when you specify a source other than nuget.org or discover packages from such a source. -::: - ## Options The following options are available: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index ee634b6371..b4ce4cbed7 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -38,11 +38,10 @@ The `--output` option validates the provided path before creating the project: - Paths that point to an **existing non-empty directory** are rejected with a clear error message. Use a different output path or an empty directory. ## Interactive prompts @@ -119,7 +118,7 @@ aspire certs trust Choosing **No** (the default) configures services with standard `http://localhost:` addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration. :::caution[Only use sources you trust] -Content from configuration sources, template repositories, and package sources can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a configuration source, fetches a Git template repository, or uses a package source other than nuget.org. Passing `--use-config-source` doesn't suppress the warning. Review sources and their referenced content before using them. See [Configuration sources](/extensibility/config-sources/). +Content selected by a configuration source can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a configuration source. Passing `--use-config-source` doesn't suppress the warning. Review the source and its referenced content before using them. See [Configuration sources](/extensibility/config-sources/). ::: ## Options @@ -142,20 +141,6 @@ The following options are available: The version of the project templates to use. -- **`--template-path `** - - Path to an unpacked template package directory. With `--template-repository`, the path is relative to the repository root. - -- **`--template-repository `** - - Git repository containing templates. The CLI fetches the repository and discovers templates at its root unless you also specify `--template-path`. - -- **`--template-repository-ref `** - - Branch, tag, or full commit ID for the template repository. Requires `--template-repository`; defaults to the repository's HEAD. - - `--template-path` and `--template-repository` can't be combined with a template subcommand, `--source`, `--version`, `--channel`, or `--language`. If the source contains multiple templates, select one interactively. - - **`--channel`** Channel to use for templates (`stable`, `staging`, `daily`). If you don't specify `--version`, `aspire new` selects a template package from the channel and prefers the version that matches the currently installed CLI/SDK. For explicit pre-release channels, such as `staging` and `daily`, it pins templates to the installed CLI/SDK version when the feed would otherwise select a newer pre-release package. For example, a `13.4` CLI using `--channel daily` won't pull `13.5` preview templates even if the daily feed contains them. If you specify `--version`, that template version is used with the selected channel. @@ -255,7 +240,7 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f aspire new aspire-go-starter --non-interactive --use-redis-cache true ``` -## Template sources +## Configuration sources and template discovery Use `aspire template source list` to list named template sources without discovering templates. It combines global template sources with sources from an accepted configuration source for that invocation. It doesn't save the inherited sources globally or in an app. @@ -267,8 +252,6 @@ aspire template source list --format json --use-config-source In table output, the command offers an available source interactively. Pass `--use-config-source false` to decline it. The CLI displays a trust warning even when `--use-config-source` supplies the choice. -The CLI also displays a trust warning when you register a template source with `aspire template source add`; passing `--yes` skips confirmation but doesn't suppress the warning. - ## Examples - Create an Aspire solution from the template. Because the template was selected (`aspire-starter`), you're prompted for the name, output folder, and template version. From 94fd6ec62c77bd3804a16116f3d2ca876eec55fe Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:12:49 +0800 Subject: [PATCH 06/14] docs: reorder config source usage sections Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../docs/extensibility/config-sources.mdx | 48 ++++++++++--------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index 42339e8f3f..674917d5b4 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -19,27 +19,12 @@ commit IDs before running the commands. ## Use a configuration source -Review the source and its referenced content before accepting its defaults. +Your organization or team maintains a configuration source to give everyone the +same starting point: approved agent skills, internal integration feeds, and +project templates. When your environment points to a source, Aspire offers it as +you create or initialize an app, and you choose whether to apply its defaults. -### Decide what to trust - -:::caution[Only use sources you trust] -Content selected by a configuration source can run code on your machine or -influence an agent's actions. Only accept publishers and content suppliers you -trust. Run Aspire commands only from trusted directories and repositories, even -when you select an AppHost in another directory. See the -[Aspire CLI overview](/reference/cli/overview/). -::: - -The CLI displays the warning "Only use sources you trust. Content from these -sources can run code on your machine." when it offers or fetches a configuration -source. `--use-config-source` and `--yes` don't suppress this warning. - -Before accepting, review the configuration repository, its linked documentation, -and every skill, feed, catalog, and template it references. Trusting the -publisher also means trusting those suppliers. - -### Opt in or out +### Create an app with a configuration source Install the [Aspire CLI](/get-started/install-cli/) and Git. Aspire fetches configuration sources using your existing Git credentials. @@ -47,8 +32,9 @@ configuration sources using your existing Git credentials. Your organization can [configure a source](#configure-the-source-settings) in your environment. When you run `aspire new` or `aspire init`, the CLI displays source details, a documentation link if provided, and a trust warning before -asking whether to use it. Accept to apply the shared defaults, or decline to -continue with standard Aspire defaults and record an app-local opt-out. +asking whether to use it. Before accepting, [decide what to +trust](#decide-what-to-trust). Accept to apply the shared defaults, or decline +to continue with standard Aspire defaults and record an app-local opt-out. To opt out of an existing app's source, replace only the `configSource` property in the app's `aspire.config.json` with: @@ -70,6 +56,24 @@ To opt in for an existing app that has no `configSource` property, run updates. If the app has an opt-out, remove that `configSource` property first, leaving other settings intact. +### Decide what to trust + +:::caution[Only use sources you trust] +Content selected by a configuration source can run code on your machine or +influence an agent's actions. Only accept publishers and content suppliers you +trust. Run Aspire commands only from trusted directories and repositories, even +when you select an AppHost in another directory. See the +[Aspire CLI overview](/reference/cli/overview/). +::: + +The CLI displays the warning "Only use sources you trust. Content from these +sources can run code on your machine." when it offers or fetches a configuration +source. `--use-config-source` and `--yes` don't suppress this warning. + +Before accepting, review the configuration repository, its linked documentation, +and every skill, feed, catalog, and template it references. Trusting the +publisher also means trusting those suppliers. + ### Understand what the source controls | Section | Purpose | From 82b0741e58f440d9a0eb6fdf9c4b20ee9c318e61 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:18:30 +0800 Subject: [PATCH 07/14] docs: add secure access guidance for config sources Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../content/docs/extensibility/config-sources.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index 674917d5b4..c77e02aaf2 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -213,6 +213,18 @@ Apply these controls to the skill, template, and catalog repositories as well as the configuration repository. Use approved HTTPS feeds/catalogs or trusted SSH transport, and keep credentials and other secrets out of published content. +### Secure access + +Require authentication to access your organization's configuration repository. +A private repository keeps internal feed locations, template sources, and skill +sources from being visible outside your organization, and limits who can read +the defaults your developers apply. + +The Aspire CLI uses the developer's existing Git credentials when they're +available. Otherwise, when it fetches a configuration source that requires +authentication, it interactively prompts the developer to authenticate with the +Git repository. + ### Pin each part of the supply chain A trusted repository can still receive an unintended change or be compromised. From 9dc7f320b497aadd52af3eecf5b890e1529b6ab2 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:26:45 +0800 Subject: [PATCH 08/14] docs: consolidate configuration source guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../content/docs/extensibility/config-sources.mdx | 13 +++++++------ .../docs/reference/cli/commands/aspire-new.mdx | 4 ++++ .../docs/reference/cli/commands/aspire-update.mdx | 14 +++----------- 3 files changed, 14 insertions(+), 17 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index c77e02aaf2..fbc7c21061 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -221,9 +221,9 @@ sources from being visible outside your organization, and limits who can read the defaults your developers apply. The Aspire CLI uses the developer's existing Git credentials when they're -available. Otherwise, when it fetches a configuration source that requires -authentication, it interactively prompts the developer to authenticate with the -Git repository. +available. During an interactive fetch, Git or its credential helper can prompt +the developer to authenticate with the repository. For non-interactive commands, +configure credentials in advance because Git can't prompt for them. ### Pin each part of the supply chain @@ -301,9 +301,10 @@ aspire new -An explicitly configured initialization-source URL can also provide a runtime-only -template discovery overlay without saving those definitions globally or into an -app. Employee detection alone doesn't enable that overlay. +After you accept an explicitly configured source, its template sources can be +used during interactive `aspire new` template discovery without saving those +definitions globally or into an app. Employee detection alone doesn't enable +this discovery. See [configuration sources and template discovery](/reference/cli/commands/aspire-new/#configuration-sources-and-template-discovery). ### Distribute settings across your organization diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index b4ce4cbed7..71c87bf8f3 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -242,6 +242,10 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f ## Configuration sources and template discovery +When `ASPIRE_INIT_SOURCE_URL` is explicitly configured and you accept the source, the interactive `aspire new` template picker can include its templates alongside templates from global sources. Declining the source excludes its template sources from discovery. Employee detection alone doesn't enable this discovery. + +If a global template source has the same name as an inherited source, the global source's entire definition takes precedence. Source names are compared case-insensitively. + Use `aspire template source list` to list named template sources without discovering templates. It combines global template sources with sources from an accepted configuration source for that invocation. It doesn't save the inherited sources globally or in an app. For JSON output, the command lists global sources without consulting a configuration source by default. Pass `--use-config-source` to accept the offered source and include its template sources: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx index 16326fefdc..0e32e40bc1 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-update.mdx @@ -47,8 +47,8 @@ The update command requires --yes when the --non-interactive option is specified ``` `--yes` doesn't consent to adopting a configuration source. By default, a normal -non-interactive update doesn't adopt a source for an app that has no binding. To -accept an available source as part of the update, also pass +non-interactive update doesn't adopt a source or save an opt-out for an app that +has no binding. To accept an available source as part of the update, also pass `--use-config-source`. To explicitly decline, pass `--use-config-source false`. Existing source bindings and opt-outs aren't changed by this option. @@ -116,7 +116,7 @@ The following options are available: - **`--config-source`** - Refresh only the nearest saved app-local [configuration source](/extensibility/config-sources/) and apply its shared settings. Supplied skill and integration sections replace the corresponding local sections, including local edits. This doesn't adopt a new source, update packages, update the SDK or CLI, regenerate templates, or reconcile existing agent registrations. If there is no active saved binding, the command reports that no source is bound and leaves the configuration unchanged. + Refresh only the nearest saved app-local [configuration source](/extensibility/config-sources/) and apply its shared settings. Supplied skill and integration sections replace the corresponding local sections, including local edits. This doesn't adopt a new source, update packages, update the SDK or CLI, regenerate templates, or reconcile existing agent registrations. If there is no active saved binding or the app has opted out, the command reports that there is no source to update and exits successfully without fetching. Can't be combined with `--self`, `--migrate`, `--channel`, `--quality`, or `--nuget-config-dir`. Non-interactive refresh also requires `--yes`. @@ -136,14 +136,6 @@ The following options are available: The `staging` channel can only be resolved from a `stable` or `staging` Aspire CLI build. Daily, local, and per-PR CLI builds don't have a deterministic staging feed, so requesting `--channel staging` from one of them fails with an error naming the running CLI's identity and pointing at the recovery options: install a staging or stable Aspire CLI, or set the `overrideStagingFeed` configuration value (for example, `aspire config set -g overrideStagingFeed `) to point at the staging feed you want to use. See [`overrideStagingFeed`](/reference/cli/configuration/#settings-surfaced-by-aspire-config) in the CLI configuration reference. -- **`--config-source`** - - Refresh the app configuration from the configuration source saved in the project's local settings file, instead of running the package update workflow. Before fetching, the command displays the saved source's repository, configuration file path (when not the default), optional ref, and declaring settings file, without repeating the introductory explanation of configuration sources. - - After a successful refresh, the command reports whether the configuration was updated to the latest version from its source or was already up to date. Restoring local edits to source-supplied values counts as an update. If the project has no saved source, or has opted out of one, the command reports that there is no configuration source to update and exits successfully without fetching. - - For automation, use `aspire update --config-source --yes --non-interactive`. - - **`-y, --yes`** Automatically confirm update prompts without user input. Use this option in CI/CD pipelines or other non-interactive environments to skip confirmation dialogs. This doesn't accept a new configuration source; use `--use-config-source` for that choice. From 3d112557bfa768bacc63e47d06461e4f6d0550aa Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:29:33 +0800 Subject: [PATCH 09/14] docs: clarify template source discovery scope Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/commands/aspire-new.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index 71c87bf8f3..a7b476e1e3 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -244,7 +244,7 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f When `ASPIRE_INIT_SOURCE_URL` is explicitly configured and you accept the source, the interactive `aspire new` template picker can include its templates alongside templates from global sources. Declining the source excludes its template sources from discovery. Employee detection alone doesn't enable this discovery. -If a global template source has the same name as an inherited source, the global source's entire definition takes precedence. Source names are compared case-insensitively. +If a global template source has the same name as an inherited source, the global source's entire definition takes precedence. Source names are compared case-insensitively. Template discovery ignores `templateSources` defined in an app's local configuration. Use `aspire template source list` to list named template sources without discovering templates. It combines global template sources with sources from an accepted configuration source for that invocation. It doesn't save the inherited sources globally or in an app. From 3e09a8656c060297e81914ddd2482f335c624dc5 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:37:24 +0800 Subject: [PATCH 10/14] docs: simplify configuration source guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/frontend/src/content/docs/extensibility/config-sources.mdx | 3 +-- .../src/content/docs/reference/cli/commands/aspire-new.mdx | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index fbc7c21061..ef15af4739 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -303,8 +303,7 @@ aspire new After you accept an explicitly configured source, its template sources can be used during interactive `aspire new` template discovery without saving those -definitions globally or into an app. Employee detection alone doesn't enable -this discovery. See [configuration sources and template discovery](/reference/cli/commands/aspire-new/#configuration-sources-and-template-discovery). +definitions globally or into an app. See [configuration sources and template discovery](/reference/cli/commands/aspire-new/#configuration-sources-and-template-discovery). ### Distribute settings across your organization diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index a7b476e1e3..5b405060f1 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -242,7 +242,7 @@ The `aspire-go-starter` template scaffolds a Go API (`api/`), a Vite and React f ## Configuration sources and template discovery -When `ASPIRE_INIT_SOURCE_URL` is explicitly configured and you accept the source, the interactive `aspire new` template picker can include its templates alongside templates from global sources. Declining the source excludes its template sources from discovery. Employee detection alone doesn't enable this discovery. +When `ASPIRE_INIT_SOURCE_URL` is explicitly configured and you accept the source, the interactive `aspire new` template picker can include its templates alongside templates from global sources. Declining the source excludes its template sources from discovery. If a global template source has the same name as an inherited source, the global source's entire definition takes precedence. Source names are compared case-insensitively. Template discovery ignores `templateSources` defined in an app's local configuration. From 0e42715794d6300aec3c795d3024d2c02f5557e5 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 13 Nov 2026 15:38:43 +0800 Subject: [PATCH 11/14] docs: document package and template source warnings Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/commands/aspire-add.mdx | 4 ++++ .../src/content/docs/reference/cli/commands/aspire-new.mdx | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx index 7e88434bd7..c27df71aac 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx @@ -40,6 +40,10 @@ The following arguments are available: If a partial name or invalid name is provided, the CLI searches NuGet for approximate matches and prints them in the terminal for the user to select. If no results are found, all packages are listed. +:::caution[Only use sources you trust] +Content from package sources can run code on your machine. The CLI displays a trust warning when you specify a package source other than nuget.org. Review the source before using it. +::: + ## Options The following options are available: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index 5b405060f1..ac9977b9ed 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -118,7 +118,7 @@ aspire certs trust Choosing **No** (the default) configures services with standard `http://localhost:` addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration. :::caution[Only use sources you trust] -Content selected by a configuration source can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a configuration source. Passing `--use-config-source` doesn't suppress the warning. Review the source and its referenced content before using them. See [Configuration sources](/extensibility/config-sources/). +Content from configuration sources, template repositories, and package sources can run code on your machine or influence an agent's actions. The CLI displays a trust warning when it offers a configuration source, uses a template repository, or is given a package source other than nuget.org. Passing `--use-config-source` doesn't suppress the warning. Review each source and its referenced content before using them. See [Configuration sources](/extensibility/config-sources/). ::: ## Options From a1e09ca7da9d33475df848c4ebcd4ec217783807 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 17 Nov 2026 13:16:40 +0800 Subject: [PATCH 12/14] docs: clarify template source scope Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/commands/aspire-new.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index ac9977b9ed..8a00474552 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -64,7 +64,7 @@ If no template sources are configured, or if you pass `--source`, `--version`, ` #### Configure template sources -A template source is a named Git repository or local directory that contains templates. Template sources are stored in global Aspire configuration and apply to every project on the machine. Use the `aspire template source` commands to manage them rather than editing the configuration file directly: +A template source is a named Git repository or local directory that contains templates. Sources added with `aspire template source add` are stored in global Aspire configuration and apply to every project on the machine. An accepted [configuration source](#configuration-sources-and-template-discovery) can also provide template sources for the current invocation without saving them globally. Use the `aspire template source` commands to manage global sources rather than editing the configuration file directly: ```bash title="Aspire CLI" aspire template source add company --repository https://github.com/example/templates From 3cb4d2322d8dc0942d345c1aecade87fb85d7b6b Mon Sep 17 00:00:00 2001 From: Maddy Montaquila Date: Tue, 17 Nov 2026 13:56:01 -0500 Subject: [PATCH 13/14] docs: explain why to use configuration sources Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../docs/extensibility/config-sources.mdx | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index ef15af4739..862802615b 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -17,6 +17,35 @@ All repositories, feeds, documentation URLs, and commit IDs in these examples ar illustrative. Replace them with your organization's locations and reviewed full commit IDs before running the commands. +## Why use a configuration source + +Platform engineering teams often maintain a "golden path": the approved tools, +packages, and starting points that help developers build apps the organization's +way. Without a shared mechanism, each developer has to find and wire up those +pieces by hand, and teams drift apart as internal guidance changes. + +A configuration source lets a platform team publish that golden path once and +offer it wherever developers create Aspire apps: + +- **Faster onboarding**: New developers start from your organization's + templates, integrations, and agent skills instead of assembling them from + internal wikis. +- **Consistent starting points**: Apps across teams begin with the same + integration feeds and project structure, which makes them easier to support + and review. +- **Internal integrations by default**: Developers can discover your + organization's hosting integrations, such as wrappers for internal services, + alongside the built-in ones. +- **Organization-aware agents**: Coding agents receive skills that describe + your conventions, so their suggestions match how your organization builds + apps. +- **Central updates**: When the platform team updates the shared configuration, + apps can pick up the change with a single command instead of hand-editing each + app. + +Developers still decide whether to accept a source, so it works as a +recommended default rather than a mandate. + ## Use a configuration source Your organization or team maintains a configuration source to give everyone the From 0b2aabf8b4a7040a5f2d787a890e83d38eabeb10 Mon Sep 17 00:00:00 2001 From: Maddy Montaquila Date: Tue, 17 Nov 2026 13:57:34 -0500 Subject: [PATCH 14/14] docs: tighten config source benefit claims Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/extensibility/config-sources.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/frontend/src/content/docs/extensibility/config-sources.mdx b/src/frontend/src/content/docs/extensibility/config-sources.mdx index 862802615b..0465c9476d 100644 --- a/src/frontend/src/content/docs/extensibility/config-sources.mdx +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -36,12 +36,12 @@ offer it wherever developers create Aspire apps: - **Internal integrations by default**: Developers can discover your organization's hosting integrations, such as wrappers for internal services, alongside the built-in ones. -- **Organization-aware agents**: Coding agents receive skills that describe - your conventions, so their suggestions match how your organization builds - apps. +- **Organization-aware agents**: Coding agents can register your + organization's skills, so their suggestions can follow how your organization + builds apps. - **Central updates**: When the platform team updates the shared configuration, - apps can pick up the change with a single command instead of hand-editing each - app. + developers can refresh an app's saved settings with a single command instead + of hand-editing each app. Developers still decide whether to accept a source, so it works as a recommended default rather than a mandate.