From c8c06ebdae9d45eb9f6b299203133864d2874630 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 19 May 2026 21:16:32 +0000 Subject: [PATCH] docs(site): document --all-repos and --source flags for secrets commands Add the two opt-in project-scope discovery flags introduced in feat(secrets): #624 to the CLI reference page: - --all-repos: activates Preview-driven discovery across the entire ADO project, not just local lock files - --source : filters to definitions whose ado-aw-metadata marker references the given template path Also adds a "Project-scope discovery" subsection with usage examples and updates the common-examples block with an --all-repos one-liner. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- site/src/content/docs/setup/cli.mdx | 31 +++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/site/src/content/docs/setup/cli.mdx b/site/src/content/docs/setup/cli.mdx index 9680b35a..be554d65 100644 --- a/site/src/content/docs/setup/cli.mdx +++ b/site/src/content/docs/setup/cli.mdx @@ -80,7 +80,9 @@ Options: - `--org ` -- Azure DevOps organization URL or bare org name - `--project ` -- Azure DevOps project name - `--pat ` -- PAT for ADO API authentication -- `--definition-ids ` -- explicit comma-separated definition IDs (skips auto-detection) +- `--definition-ids ` -- explicit comma-separated definition IDs (skips auto-detection); mutually exclusive with `--all-repos` / `--source` +- `--all-repos` -- **project-scope mode**: search every ado-aw definition in the ADO project, not just those with a local lock file; mutually exclusive with `--definition-ids` +- `--source ` -- filter to definitions whose `# ado-aw-metadata` marker references this template path (e.g. `agents/security-scan.md`); activates the discovery code path; pairs with `--all-repos` to scope across the whole project - `--dry-run` -- print the planned set without calling the ADO API ### `secrets list [path]` @@ -91,6 +93,7 @@ Options: - `--json` -- emit machine-readable JSON - `--org`, `--project`, `--pat`, `--definition-ids` -- same as `secrets set` +- `--all-repos`, `--source` -- same as `secrets set` ### `secrets delete [path]` @@ -99,8 +102,29 @@ Delete a named variable from every matched definition. No-op when the variable i Options: - `--org`, `--project`, `--pat`, `--definition-ids` -- same as `secrets set` +- `--all-repos`, `--source` -- same as `secrets set` - `--dry-run` -- print the planned deletion without calling the ADO API +### Project-scope discovery (`--all-repos` / `--source`) + +By default, `secrets` commands match ADO definitions by scanning local lock files. Two opt-in flags activate **Preview-driven discovery** instead — useful when local checkouts of every consumer pipeline aren't available: + +- **`--all-repos`** — search every ado-aw definition in the ADO project, including consumer pipelines that include ado-aw templates but live in other repos. No local checkout of those repos is required. +- **`--source `** — restrict results to definitions whose `# ado-aw-metadata` marker references the given template path. Useful for fan-out token rotation: `ado-aw secrets set GITHUB_TOKEN --source agents/security-scan.md` updates every pipeline that includes that template across the entire project. + +Both flags are mutually exclusive with `--definition-ids`. `enable`, `disable`, and `remove` are **not** affected — they retain their source-scoped safety semantics. + +```bash +# Rotate GITHUB_TOKEN on every ado-aw pipeline in the project +ado-aw secrets set GITHUB_TOKEN --all-repos + +# Update only pipelines that include a specific template +ado-aw secrets set GITHUB_TOKEN --all-repos --source agents/security-scan.md + +# Preview which definitions would be updated +ado-aw secrets set GITHUB_TOKEN --all-repos --dry-run +``` + ### `enable [path]` Register an ADO build definition for each compiled pipeline discovered under `path` and ensure it is `enabled`. Matches existing definitions by YAML filename first, then by display name; creates a new definition when no match is found. @@ -240,9 +264,12 @@ ado-aw compile # Verify a generated pipeline ado-aw check agent.lock.yml -# Set GITHUB_TOKEN on all matched pipelines +# Set GITHUB_TOKEN on all matched pipelines (local lock files) ado-aw secrets set GITHUB_TOKEN +# Set GITHUB_TOKEN on every ado-aw pipeline in the project (no local checkout needed) +ado-aw secrets set GITHUB_TOKEN --all-repos + # Register pipelines with ADO and set their token in one step ado-aw enable --also-set-token