You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guides/environment-overrides.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,8 @@ apiops publish \
27
27
28
28
If you ran `apiops init`, a Copilot prompt file was generated at `.github/prompts/apiops-configure-overrides.prompt.md`. Open it in VS Code and ask GitHub Copilot to help you configure environment overrides — it will guide you through setting up environment-specific values interactively.
29
29
30
+
If you didn't run `apiops init`, you can copy the prompt directly from the repository: [`src/templates/copilot/configure-overrides-prompt.md`](https://github.com/Azure/apiops-cli/blob/main/src/templates/copilot/configure-overrides-prompt.md). Save it as `.github/prompts/apiops-configure-overrides.prompt.md` in your repo and open it in VS Code.
31
+
30
32
## IDE Autocompletion with JSON Schema
31
33
32
34
A JSON Schema is available for `configuration.{env}.yaml` override files. Add yaml-language-server comment at the top of your override file. Requires yaml language extension in VSCode.
Copy file name to clipboardExpand all lines: docs/guides/filtering-resources.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -354,3 +354,5 @@ backends:
354
354
## Copilot-Assisted Configuration
355
355
356
356
If you ran `apiops init`, a Copilot prompt file was generated at `.github/prompts/apiops-configure-filter.prompt.md`. Open it in VS Code and ask GitHub Copilot to help you configure your filter — it will walk you through selecting resources interactively.
357
+
358
+
If you didn't run `apiops init`, you can copy the prompt directly from the repository: [`src/templates/copilot/configure-filter-prompt.md`](https://github.com/Azure/apiops-cli/blob/main/src/templates/copilot/configure-filter-prompt.md). Save it as `.github/prompts/apiops-configure-filter.prompt.md` in your repo and open it in VS Code.
> **How to use:** Open this file in VS Code with GitHub Copilot and ask
9
-
> Copilot to help you design a `configuration.extractor.yaml` file for your
10
-
> repository.
8
+
> **How to use:** Open this file in VS Code with GitHub Copilot and ask Copilot to help you design a `configuration.extractor.yaml` file for your repository.
11
9
12
10
## Goal
13
11
14
-
Create a `configuration.extractor.yaml` file that limits APIOps extraction to
15
-
the Azure API Management resources your team wants to manage in source control.
12
+
Create a `configuration.extractor.yaml` file that limits APIOps extraction to the Azure API Management resources your team wants to manage in source control.
16
13
17
14
---
18
15
19
16
## How Copilot must work through this prompt
20
17
21
18
These rules apply to **every** step below. Follow them strictly:
22
19
23
-
1.**Confirm before proceeding.** At the end of every step, summarize what you
24
-
learned or propose, then **STOP and wait for the user to confirm** before
25
-
moving to the next step. Never chain steps together without an explicit
26
-
"yes" / "go ahead" from the user.
27
-
-**Hard stop rule:** When you ask for confirmation, end the response there.
28
-
Do **not** include the next question, next resource type, or any forward
29
-
action in the same message.
30
-
- This hard stop applies to **step boundaries** (Step 0, Step 2, Step 3,
31
-
Step 4). In Step 1, follow the single-resource-type cadence below.
32
-
2.**Never assume or invent names.** Do not invent API, product, backend,
33
-
named value, or any other resource names. Use only names that come from the
34
-
live APIM instance or that the user explicitly provides. The local artifact
35
-
directory is not authoritative — it may be stale or empty. When unsure, ask.
36
-
3.**Default is extract-everything.** APIOps extracts **all** resources of a
37
-
type when that type is **omitted** from the filter. Only add a type to the
38
-
filter when the user wants to narrow it (SOME) or exclude it (NONE). Do not
39
-
add a type just to list every resource.
40
-
4.**Empty array means exclude all.** Setting a type to `[]` excludes every
41
-
resource of that type. Use this only when the user explicitly wants NONE.
42
-
5.**The JSON schema is the source of structure.** To determine which resource
43
-
types support sub-entries and what those sub-entries are (for example,
44
-
`apis` → `operations`, `diagnostics`, `schemas`, `releases`), consult the
45
-
`extractor-config` JSON schema referenced in the file's
46
-
`# yaml-language-server: $schema=...` comment (the public schema URL).
20
+
1.**Confirm before proceeding.** At the end of every step, summarize what you learned or propose, then **STOP and wait for the user to confirm** before moving to the next step. Never chain steps together without an explicit "yes" / "go ahead" from the user.
21
+
-**Hard stop rule:** When you ask for confirmation, end the response there. Do **not** include the next question, next resource type, or any forward action in the same message.
22
+
- This hard stop applies to **step boundaries** (Step 0, Step 2, Step 3, Step 4). In Step 1, follow the single-resource-type cadence below.
23
+
2.**Never assume or invent names.** Do not invent API, product, backend, named value, or any other resource names. Use only names that come from the live APIM instance or that the user explicitly provides. The local artifact directory is not authoritative — it may be stale or empty. When unsure, ask.
24
+
3.**Default is extract-everything.** APIOps extracts **all** resources of a type when that type is **omitted** from the filter. Only add a type to the filter when the user wants to narrow it (SOME) or exclude it (NONE). Do not add a type just to list every resource.
25
+
4.**Empty array means exclude all.** Setting a type to `[]` excludes every resource of that type. Use this only when the user explicitly wants NONE.
26
+
5.**The JSON schema is the source of structure.** To determine which resource types support sub-entries and what those sub-entries are (for example, `apis` → `operations`, `diagnostics`, `schemas`, `releases`), consult the `extractor-config` JSON schema referenced in the file's `# yaml-language-server: $schema=...` comment (the public schema URL).
47
27
48
28
---
49
29
50
30
## Step 0 — Determine the Authoritative Resource List
51
31
52
-
The filter runs at **extraction time against the live Azure API Management
53
-
instance**. The local artifact directory may be stale, partial, or empty, so it
54
-
is **not** an authoritative list of what exists in Azure. Establish the source
55
-
of truth first:
56
-
57
-
1.**Prefer querying the live APIM instance.** Ask the user for (or reuse if
58
-
already known) the subscription ID, resource group, and APIM service name,
59
-
and whether the Azure CLI is logged in. If Azure is reachable, enumerate the
60
-
resource types and names directly from the instance (for example with
61
-
`az apim` / `az rest` calls) and use that as the source of truth.
62
-
2.**Fallback when Azure cannot be queried.** Do **not** treat the local
63
-
artifacts as the definitive list. Instead, in Step 1 ask the user
64
-
type-by-type; for SOME, the user must provide the resource (and
65
-
sub-resource) names themselves.
66
-
3. Check whether `configuration.extractor.yaml` already exists (it may have
67
-
been created by `apiops init`). If it exists, note its current contents —
68
-
you will update it in place rather than overwriting it.
69
-
70
-
Tell the user which mode you will use (live-Azure list vs. user-provided
71
-
names), and confirm the connection details if querying Azure.
32
+
The filter runs at **extraction time against the live Azure API Management instance**. The local artifact directory may be stale, partial, or empty, so it is **not** an authoritative list of what exists in Azure. Establish the source of truth first:
33
+
34
+
1.**Prefer querying the live APIM instance.** Ask the user for (or reuse if already known) the subscription ID, resource group, and APIM service name, and whether the Azure CLI is logged in. If Azure is reachable, enumerate the resource types and names directly from the instance (for example with `az apim` / `az rest` calls) and use that as the source of truth.
35
+
2.**Fallback when Azure cannot be queried.** Do **not** treat the local artifacts as the definitive list. Instead, in Step 1 ask the user type-by-type; for SOME, the user must provide the resource (and sub-resource) names themselves.
36
+
3. Check whether `configuration.extractor.yaml` already exists (it may have been created by `apiops init`). If it exists, note its current contents — you will update it in place rather than overwriting it.
37
+
38
+
Tell the user which mode you will use (live-Azure list vs. user-provided names), and confirm the connection details if querying Azure.
72
39
73
40
**STOP. Do not proceed until the user confirms the source of truth.**
74
41
75
42
---
76
43
77
44
## Step 1 — Decide Scope Per Resource Type (one type at a time)
78
45
79
-
Walk through the resource types **one type at a time**. For each type, ask the
80
-
user which scope they want:
46
+
Walk through the resource types **one type at a time**. For each type, ask the user which scope they want:
81
47
82
-
-**Extract ALL** — include every resource of this type. Leave this type
83
-
**out** of the filter (APIOps extracts everything by default).
84
-
-**Extract NONE** — exclude all resources of this type. Add the type with an
85
-
empty array: `tags: []`.
86
-
-**Extract SOME** — include only specific resources. The user provides which
87
-
names (or wildcard patterns) to include. Matching is case-insensitive and
88
-
supports `*` and `?` wildcards.
48
+
-**Extract ALL** — include every resource of this type. Leave this type **out** of the filter (APIOps extracts everything by default).
49
+
-**Extract NONE** — exclude all resources of this type. Add the type with an empty array: `tags: []`.
50
+
-**Extract SOME** — include only specific resources. The user provides which names (or wildcard patterns) to include. Matching is case-insensitive and supports `*` and `?` wildcards.
89
51
90
52
**Single-resource-type cadence for Step 1:**
91
53
92
-
- Ask about exactly **one** resource type at a time. Do not batch multiple
93
-
types into one prompt.
94
-
-**Ask ALL / NONE / SOME first.** Do **not** enumerate or query any names up
95
-
front. For ALL or NONE, record the answer and move on — no enumeration is
96
-
needed.
54
+
- Ask about exactly **one** resource type at a time. Do not batch multiple types into one prompt.
55
+
-**Ask ALL / NONE / SOME first.** Do **not** enumerate or query any names up front. For ALL or NONE, record the answer and move on — no enumeration is needed.
97
56
-**Only when the user answers SOME**, then gather names:
98
-
- If you can query the live APIM instance, list that type's names from Azure
99
-
to help the user choose.
100
-
- Otherwise, ask the user to provide the names/patterns. Do **not** invent
101
-
names or pull them from the local artifacts.
102
-
- When the user answers a type unambiguously, record the decision and move to
103
-
the next type.
104
-
-**Update `configuration.extractor.yaml` immediately after each decision that
105
-
affects the file** (SOME or NONE adds/updates that type's section; ALL means
106
-
no change since the type is omitted). Keep the file in sync as you go rather
107
-
than waiting until the end.
57
+
- If you can query the live APIM instance, list that type's names from Azure to help the user choose.
58
+
- Otherwise, ask the user to provide the names/patterns. Do **not** invent names or pull them from the local artifacts.
59
+
- When the user answers a type unambiguously, record the decision and move to the next type.
60
+
-**Update `configuration.extractor.yaml` immediately after each decision that affects the file** (SOME or NONE adds/updates that type's section; ALL means no change since the type is omitted). Keep the file in sync as you go rather than waiting until the end.
108
61
- Only pause for clarification when the answer is ambiguous.
109
62
110
-
Resource types to consider (ask only about types that exist in the
111
-
instance/artifacts or that the user mentions):
63
+
Resource types to consider (ask only about types that exist in the instance/artifacts or that the user mentions):
> **APIs can be filtered at the sub-resource level.** Whenever `apis` is SOME
118
-
> and specific API names are listed in the filter, **ask about each listed
119
-
> API's sub-resources** — `operations`, `diagnostics`, `schemas`, and
120
-
> `releases`. The user may want everything for that API, or only a subset
121
-
> (for example, a single revision or release). Omit a sub-filter to include
122
-
> all of that sub-type; set it to `[]` to exclude all.
67
+
> **APIs can be filtered at the sub-resource level.** Whenever `apis` is SOME and specific API names are listed in the filter, **ask about each listed API's sub-resources** — `operations`, `diagnostics`, `schemas`, and `releases`. The user may want everything for that API, or only a subset (for example, a single revision or release). Omit a sub-filter to include all of that sub-type; set it to `[]` to exclude all.
123
68
124
-
> **Workspaces apply only if the APIM instance uses workspaces.** Skip this
125
-
> type entirely if there are no workspaces. When a user wants SOME for
126
-
> `workspaces`, each workspace can also be narrowed by its own sub-resources
> `versionSets`). Omit a sub-filter to include all of that sub-type; set it to
130
-
> `[]` to exclude all. Only offer this depth if the user wants it.
69
+
> **Workspaces apply only if the APIM instance uses workspaces.** Skip this type entirely if there are no workspaces. When a user wants SOME for `workspaces`, each workspace can also be narrowed by its own sub-resources (`apis`, `backends`, `diagnostics`, `groups`, `loggers`, `namedValues`, `policyFragments`, `products`, `schemas`, `subscriptions`, `tags`, `versionSets`). Omit a sub-filter to include all of that sub-type; set it to `[]` to exclude all. Only offer this depth if the user wants it.
131
70
132
-
> **Service-level `policies` is effectively a single global policy.** For this
133
-
> type, ask only **include (ALL)** or **exclude (NONE)** — SOME does not apply.
71
+
> **Service-level `policies` is effectively a single global policy.** For this type, ask only **include (ALL)** or **exclude (NONE)** — SOME does not apply.
134
72
135
-
After all types are decided, summarize the per-type decisions and **STOP for
136
-
confirmation** before generating YAML.
73
+
After all types are decided, summarize the per-type decisions and **STOP for confirmation** before generating YAML.
137
74
138
75
---
139
76
140
77
## Step 2 — Propose a Filter Strategy
141
78
142
79
Based on the recorded decisions:
143
80
144
-
1. Recommend the smallest filter that safely captures the intended scope
145
-
(remember: omitted types are fully extracted, so only NONE/SOME types
146
-
appear in the file).
81
+
1. Recommend the smallest filter that safely captures the intended scope (remember: omitted types are fully extracted, so only NONE/SOME types appear in the file).
147
82
2. Explain any tradeoffs between broad and narrow filters.
148
-
3. Call out any risk of accidentally excluding required dependencies — for
149
-
example, excluding a named value or backend that an included API's policy
150
-
references.
83
+
3. Call out any risk of accidentally excluding required dependencies — for example, excluding a named value or backend that an included API's policy references.
151
84
152
-
If the user is unsure, recommend a conservative filter that is easy to refine,
153
-
then **STOP for confirmation**.
85
+
If the user is unsure, recommend a conservative filter that is easy to refine, then **STOP for confirmation**.
> **Note:** The file `configuration.extractor.yaml` may already exist if the
160
-
> user ran `apiops init`. If it exists, **update it in place** rather than
161
-
> overwriting unrelated content.
91
+
> **Note:** The file `configuration.extractor.yaml` may already exist if the user ran `apiops init`. If it exists, **update it in place** rather than overwriting unrelated content.
162
92
163
93
Create the YAML file content reflecting the confirmed decisions.
164
94
165
95
Requirements:
166
96
167
-
-**Preserve the existing schema comment.** If the file already has a
168
-
`# yaml-language-server: $schema=...` line (as `apiops init` generates), keep
169
-
it **exactly as-is** — it already points at the correct schema version. Only
170
-
if the file has **no** schema comment, add one referencing the current schema
171
-
version:
97
+
-**Preserve the existing schema comment.** If the file already has a `# yaml-language-server: $schema=...` line (as `apiops init` generates), keep it **exactly as-is** — it already points at the correct schema version. Only if the file has **no** schema comment, add one referencing the current schema version:
0 commit comments