diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index 5085b76fa..d7741f947 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -1169,6 +1169,10 @@ export const docsTopics = { slug: 'extensibility/typescript-hosting-integrations', badge: 'Experimental', }, + { + label: 'Configuration sources', + slug: 'extensibility/config-sources', + }, ], }, { 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 000000000..0465c9476 --- /dev/null +++ b/src/frontend/src/content/docs/extensibility/config-sources.mdx @@ -0,0 +1,345 @@ +--- +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 +your organization's needs. + +These are optional defaults, not enforced policy. Developers can decline a source +or edit the resulting app configuration. + +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. + +## 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 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, + 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. + +## Use a configuration source + +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. + +### 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. + +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. 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: + +```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. + +### 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 | +| -------------------- | ------------------------------------------------------------------------ | +| `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 +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 +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: + +```bash title="Refresh the saved configuration source" +aspire update --config-source +``` + +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. + +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 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 + +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 +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 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 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 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. + +### 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. 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 + +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 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 + +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 terminal session before distributing them: + + +
+ +```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' +$env:ASPIRE_INIT_SOURCE_README_URL = 'https://engineering.contoso.com/aspire' +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. See [configuration sources and template discovery](/reference/cli/commands/aspire-new/#configuration-sources-and-template-discovery). + +### 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-add.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx index 7e88434bd..c27df71aa 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-init.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx index ab7dd40f4..29355da6f 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: @@ -129,6 +133,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 +195,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 45229351b..8a0047455 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,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 @@ -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 @@ -117,6 +117,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, 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 The following options are available: @@ -165,7 +169,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`** @@ -234,6 +240,22 @@ 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 ``` +## 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. + +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. + +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. + ## 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. @@ -260,6 +282,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 ae3f8e768..0e32e40bc 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 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. + ### 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. @@ -94,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: @@ -104,6 +114,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 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`. + +- **`--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. @@ -114,17 +136,9 @@ 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 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 +176,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 291d3e964..15a090024 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