Skip to content

Commit 03fe887

Browse files
EMaherCopilotCopilot
authored
feat(init): rename and rewrite identity setup output files (#200)
* feat(init): rename output files and rewrite manual guides for UI focus - Rename manual guide: IDENTITY-SETUP-GITHUB.md → APIOPS-WORKFLOW-IDENTITY-SETUP.md - Rename manual guide: IDENTITY-SETUP-AZDO.md → APIOPS-PIPELINE-IDENTITY-SETUP.md - Rename prompt: apiops-setup-identity.prompt.md → apiops-setup-{workflow|pipeline}-identity.prompt.md - Rewrite manual guides to focus on web UI steps with documentation links - Add note about identity distinction (Azure access vs PR creation) - Add reference to prompt file in manual guides * docs: update Azure DevOps identity guide title * docs: add official doc links to all UI navigation steps Adds a reference link to the relevant Microsoft/GitHub docs page above every section that instructs the user to navigate a web UI, so readers have a fallback if the UI changes. * refactor: remove all token injection from manual identity guides Manual guide markdown files are now fully static with generic 'for each environment' instructions. No more dynamic rendering — the identity-guide-service just returns the template content as-is. This makes the guides easier to maintain. * refactor: inline Azure DevOps core template into prompt file Combines src/templates/shared/identity-setup-azure-devops-core.md directly into the Azure DevOps prompt template, eliminating a level of indirection. The two dynamic tokens (ENVIRONMENTS_ARRAY_POWERSHELL/BASH) are now rendered directly in the prompt template. * docs: add prompt files documentation (#201) Describes available prompt files, how to download them individually (bash and PowerShell), and how to use them in VS Code and GitHub Copilot CLI. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent 6384aef commit 03fe887

18 files changed

Lines changed: 873 additions & 902 deletions

docs/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ docs/
6666
│ ├── multi-team-workflows.md — Selective extraction, CODEOWNERS
6767
│ ├── code-first-workflow.md — IDE → git → CI/CD → APIM
6868
│ ├── token-substitution.md — Pipeline token/placeholder substitution
69+
│ ├── prompt-files.md — Copilot prompt files for APIOps tasks
6970
│ └── migration-from-v1.md — Migrate from Azure/apiops toolkit
7071
├── ci-cd/
7172
│ ├── github-actions.md — GitHub Actions integration

docs/commands/init.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,27 +78,28 @@ In interactive mode (the default when running in a terminal), `apiops init` prom
7878

7979
| File | Purpose |
8080
|------|---------|
81-
| `.github/workflows/run-apim-extractor.yml` | Workflow to extract APIM artifacts |
82-
| `.github/workflows/run-apim-publisher.yml` | Workflow to publish artifacts to APIM |
81+
| `.github/workflows/run-apiops-extractor.yml` | Workflow to extract APIM artifacts |
82+
| `.github/workflows/run-apiops-publisher.yml` | Workflow to publish artifacts to APIM |
8383
| `configuration.extractor.yaml` | Sample filter configuration for extraction |
8484
| `configuration.{env}.yaml` | Override templates per environment (e.g., `configuration.dev.yaml`, `configuration.prod.yaml`) |
85-
| `IDENTITY-SETUP-GITHUB.md` | Step-by-step guide for configuring federated credentials |
85+
| `.github/prompts/apiops-setup-workflow-identity.prompt.md` | Copilot prompt for GitHub Actions identity setup |
86+
| `APIOPS-WORKFLOW-IDENTITY-SETUP.md` | Step-by-step guide for configuring GitHub Actions Azure access and workflow identity |
8687

8788
### Azure DevOps (`--ci azure-devops`)
8889

8990
| File | Purpose |
9091
|------|---------|
91-
| `.azdo/pipelines/run-apim-extractor.yml` | Pipeline to extract APIM artifacts |
92-
| `.azdo/pipelines/run-apim-publisher.yml` | Pipeline to publish artifacts to APIM |
92+
| `.azdo/pipelines/run-apiops-extractor.yml` | Pipeline to extract APIM artifacts |
93+
| `.azdo/pipelines/run-apiops-publisher.yml` | Pipeline to publish artifacts to APIM |
9394
| `configuration.extractor.yaml` | Sample filter configuration for extraction |
9495
| `configuration.{env}.yaml` | Override templates per environment |
95-
| `IDENTITY-SETUP-AZDO.md` | Step-by-step guide for configuring service connections |
96+
| `.github/prompts/apiops-setup-pipeline-identity.prompt.md` | Copilot prompt for Azure DevOps identity setup |
97+
| `APIOPS-PIPELINE-IDENTITY-SETUP.md` | Step-by-step guide for configuring Azure DevOps pipeline identity and repo permissions |
9698

9799
### Both platforms
98100

99101
| File | Purpose |
100102
|------|---------|
101-
| `.github/prompts/apiops-setup-identity.prompt.md` | Copilot prompt for identity setup |
102103
| `.github/prompts/apiops-configure-filter.prompt.md` | Copilot prompt for creating extraction filter files |
103104
| `.github/prompts/apiops-configure-overrides.prompt.md` | Copilot prompt for creating environment override files |
104105
| `<artifact-dir>/` | Empty artifact directory (default: `./apim-artifacts`) |
@@ -118,7 +119,7 @@ If you pass `--cli-package <path>`, the tarball is copied into a `.apiops/` dire
118119

119120
## Next steps after init
120121

121-
1. **Set up identity** — Follow the generated `IDENTITY-SETUP-*.md` guide to configure Azure credentials for your CI/CD platform. Or use the `.github/prompts/apiops-setup-identity.prompt.md` Copilot prompt.
122+
1. **Set up identity** — Follow the generated `APIOPS-*-IDENTITY-SETUP.md` guide or provider-specific Copilot prompt to configure Azure credentials for your CI/CD platform.
122123
2. **Extract your first snapshot** — Run [`apiops extract`](./extract.md) to pull your current APIM configuration into the artifact directory.
123124
3. **Configure filters** — Edit `configuration.extractor.yaml` to control which resources are extracted. Use the `.github/prompts/apiops-configure-filter.prompt.md` Copilot prompt for guided setup.
124125
4. **Commit and push** — Check the generated files into version control.

docs/guides/prompt-files.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Prompt Files
2+
3+
APIOps provides [prompt files](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-prompt-files-experimental) that guide GitHub Copilot through common APIOps configuration tasks. These are reusable `.prompt.md` files that give Copilot the context it needs to help you configure extraction filters, environment overrides, and CI/CD identity setup.
4+
5+
## What are prompt files?
6+
7+
Prompt files are markdown files with a `.prompt.md` extension that provide instructions and context to GitHub Copilot. When you open a prompt file in VS Code and invoke Copilot, it uses the file's content as context to guide you through a task interactively.
8+
9+
## Available prompt files
10+
11+
| File | Description |
12+
|------|-------------|
13+
| `apiops-configure-filter.prompt.md` | Guides Copilot through creating a `configuration.extractor.yaml` filter file to control which API Management resources are extracted. See also: [Filtering resources guide](./filtering-resources.md) |
14+
| `apiops-configure-overrides.prompt.md` | Guides Copilot through creating environment override files (`configuration.<env>.yaml`) for promoting APIs across environments. See also: [Environment overrides guide](./environment-overrides.md) |
15+
| `apiops-setup-workflow-identity-github-actions.prompt.md` | Walks through setting up Azure identity (app registration, federated credentials, RBAC) for GitHub Actions CI/CD pipelines. |
16+
| `apiops-setup-workflow-identity-azure-devops.prompt.md` | Walks through setting up Azure identity (app registration, federated credentials, RBAC) for Azure DevOps CI/CD pipelines. |
17+
18+
## Getting prompt files
19+
20+
### Via `apiops init` (recommended)
21+
22+
The easiest way to get prompt files is to run [`apiops init`](../commands/init.md), which scaffolds your repository with prompt files already in place at `.github/prompts/`.
23+
24+
### Download individually
25+
26+
If you already have an APIOps repository and want to add prompt files without re-running init, you can download them directly from this repository.
27+
28+
#### Bash
29+
30+
```bash
31+
# Resolve repo root so this works from any subdirectory
32+
repo_root="$(git rev-parse --show-toplevel)"
33+
34+
# Create the prompts directory
35+
mkdir -p "${repo_root}/.github/prompts"
36+
37+
# Available prompt files — remove any you don't need
38+
files=(
39+
"apiops-configure-filter.prompt.md"
40+
"apiops-configure-overrides.prompt.md"
41+
# Remove the identity setup prompt that doesn't apply to your CI provider:
42+
"apiops-setup-workflow-identity-github-actions.prompt.md"
43+
"apiops-setup-workflow-identity-azure-devops.prompt.md"
44+
)
45+
46+
base_url="https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot"
47+
48+
for file in "${files[@]}"; do
49+
curl -sL "${base_url}/${file}" -o "${repo_root}/.github/prompts/${file}"
50+
echo "Downloaded ${file}"
51+
done
52+
```
53+
54+
#### PowerShell
55+
56+
```powershell
57+
# Resolve repo root so this works from any subdirectory
58+
$repoRoot = git rev-parse --show-toplevel
59+
60+
# Create the prompts directory
61+
New-Item -ItemType Directory -Path "$repoRoot/.github/prompts" -Force | Out-Null
62+
63+
# Available prompt files — remove any you don't need
64+
$files = @(
65+
"apiops-configure-filter.prompt.md"
66+
"apiops-configure-overrides.prompt.md"
67+
# Remove the identity setup prompt that doesn't apply to your CI provider:
68+
"apiops-setup-workflow-identity-github-actions.prompt.md"
69+
"apiops-setup-workflow-identity-azure-devops.prompt.md"
70+
)
71+
72+
$baseUrl = "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot"
73+
74+
foreach ($file in $files) {
75+
Invoke-WebRequest -Uri "$baseUrl/$file" -OutFile "$repoRoot/.github/prompts/$file"
76+
Write-Host "Downloaded $file"
77+
}
78+
```
79+
80+
## Further reading
81+
82+
- [VS Code: Reusable prompt files](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-prompt-files-experimental)
83+
- [GitHub Copilot in the CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli)

docs/walkthrough/air-gapped-azure-devops-local-registry.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -162,11 +162,11 @@ This generates:
162162
| File | Purpose |
163163
|------|---------|
164164
| `package.json` | Declares the CLI as a dependency |
165-
| `pipelines/run-extractor.yaml` | Extract pipeline |
166-
| `pipelines/run-publisher.yaml` | Publish pipeline |
165+
| `.azdo/pipelines/run-apiops-extractor.yml` | Extract pipeline |
166+
| `.azdo/pipelines/run-apiops-publisher.yml` | Publish pipeline |
167167
| `configuration.*.yaml` | Override templates |
168168

169-
Follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md` or run `/apiops-setup-identity` prompt. This creates the necessary variable groups and and service connections.
169+
Follow the remaining instructions listed in created `APIOPS-PIPELINE-IDENTITY-SETUP.md` or run `/apiops-setup-pipeline-identity` prompt. This creates the necessary variable groups and service connections.
170170

171171
### 2.2 Generate the Lock File
172172

@@ -178,7 +178,7 @@ This creates `package-lock.json`. Commit it — the lock file is **required** fo
178178

179179
### 2.3 Modify Pipelines for Air-Gapped Operation
180180

181-
The generated pipelines (`pipelines/run-extractor.yaml` and `pipelines/run-publisher.yaml`) need the following edits:
181+
The generated pipelines (`.azdo/pipelines/run-apiops-extractor.yml` and `.azdo/pipelines/run-apiops-publisher.yml`) need the following edits:
182182

183183
| Edit | What to Change |
184184
|------|----------------|
@@ -207,17 +207,17 @@ Commit the files required to run the local-registry workflow on self-hosted agen
207207
| `.npmrc` | Points npm to the local Azure Artifacts feed (`registry=...`, `always-auth=true`). |
208208
| `package.json` | Declares the CLI dependency. |
209209
| `package-lock.json` | Required for deterministic installs with `npm ci`. |
210-
| `pipelines/run-extractor.yaml` | Azure DevOps extract pipeline definition. |
211-
| `pipelines/run-publisher.yaml` | Azure DevOps publish pipeline definition. |
210+
| `.azdo/pipelines/run-apiops-extractor.yml` | Azure DevOps extract pipeline definition. |
211+
| `.azdo/pipelines/run-apiops-publisher.yml` | Azure DevOps publish pipeline definition. |
212212
| `configuration.*.yaml` | Generated environment override templates. |
213213

214214
```bash
215215
git add \
216216
.npmrc \
217217
package.json \
218218
package-lock.json \
219-
pipelines/run-extractor.yaml \
220-
pipelines/run-publisher.yaml \
219+
.azdo/pipelines/run-apiops-extractor.yml \
220+
.azdo/pipelines/run-apiops-publisher.yml \
221221
configuration.*.yaml
222222
git commit -m "chore: commit local-registry apiops bootstrap files"
223223
git push
@@ -245,7 +245,7 @@ Verify the following:
245245

246246
## 4 - Finish `apiops init` for pipeline
247247

248-
If not already done, while on the air-gapped network, follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md`. This creates the necessary variable groups and and service connections.
248+
If not already done, while on the air-gapped network, follow the remaining instructions listed in created `APIOPS-PIPELINE-IDENTITY-SETUP.md`. This creates the necessary variable groups and service connections.
249249

250250
---
251251

docs/walkthrough/air-gapped-azure-devops-offline-tarball.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -78,11 +78,11 @@ This command generates:
7878
| File | Purpose |
7979
|------|---------|
8080
| `package.json` | Declares the CLI as a `file:` dependency pointing at the tarball |
81-
| `pipelines/run-extractor.yaml` | Extract pipeline |
82-
| `pipelines/run-publisher.yaml` | Publish pipeline |
81+
| `.azdo/pipelines/run-apiops-extractor.yml` | Extract pipeline |
82+
| `.azdo/pipelines/run-apiops-publisher.yml` | Publish pipeline |
8383
| `configuration.*.yaml` | Override templates |
8484

85-
Follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md` or run `/apiops-setup-identity` prompt. This creates the necessary variable groups and and service connections.
85+
Follow the remaining instructions listed in created `APIOPS-PIPELINE-IDENTITY-SETUP.md` or run `/apiops-setup-pipeline-identity` prompt. This creates the necessary variable groups and service connections.
8686

8787
### 2.2 Generate the Lock File and Pre-Stage the npm Cache
8888

@@ -97,7 +97,7 @@ npm ci # populates ~/.npm/_cacache/ with every package the lock file refe
9797
9898
### 2.3 Modify Pipelines for Air-Gapped Operation
9999

100-
The generated pipelines (`pipelines/run-extractor.yaml` and `pipelines/run-publisher.yaml`) need the following edits:
100+
The generated pipelines (`.azdo/pipelines/run-apiops-extractor.yml` and `.azdo/pipelines/run-apiops-publisher.yml`) need the following edits:
101101

102102
| Edit | What to Change |
103103
|------|----------------|
@@ -114,17 +114,17 @@ For the offline-tarball workflow, commit the files that make the pipeline fully
114114
| `.apiops/peterhauge-apiops-cli-<version>.tgz` | CLI package consumed by the pipelines. |
115115
| `package.json` | Contains the `file:` dependency pointing to the tarball. |
116116
| `package-lock.json` | Required for deterministic offline installs with `npm ci --offline`. |
117-
| `pipelines/run-extractor.yaml` | Azure DevOps extract pipeline definition. |
118-
| `pipelines/run-publisher.yaml` | Azure DevOps publish pipeline definition. |
117+
| `.azdo/pipelines/run-apiops-extractor.yml` | Azure DevOps extract pipeline definition. |
118+
| `.azdo/pipelines/run-apiops-publisher.yml` | Azure DevOps publish pipeline definition. |
119119
| `configuration.*.yaml` | Generated environment override templates. |
120120

121121
```bash
122122
git add \
123123
.apiops/peterhauge-apiops-cli-*.tgz \
124124
package.json \
125125
package-lock.json \
126-
pipelines/run-extractor.yaml \
127-
pipelines/run-publisher.yaml \
126+
.azdo/pipelines/run-apiops-extractor.yml \
127+
.azdo/pipelines/run-apiops-publisher.yml \
128128
configuration.*.yaml
129129
git commit -m "chore: commit offline-tarball apiops bootstrap files"
130130
git push
@@ -164,7 +164,7 @@ tar -xzf npm-cacache.tar.gz -C ~/.npm
164164

165165
## 4 - Finish `apiops init` for pipeline
166166

167-
If not already done, while on the air-gapped network, follow the remaining instructions listed in created `IDENTITY-SETUP-AZDO.md`. This creates the necessary variable groups and and service connections.
167+
If not already done, while on the air-gapped network, follow the remaining instructions listed in created `APIOPS-PIPELINE-IDENTITY-SETUP.md`. This creates the necessary variable groups and service connections.
168168

169169
## 5 — Commit and Validate
170170

scripts/embed-markdown-templates.mjs

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,6 @@ const templates = [
2121
exportName: 'copilotConfigureOverridesPromptTemplate',
2222
path: 'src/templates/copilot/configure-overrides-prompt.md',
2323
},
24-
{
25-
exportName: 'azureDevOpsIdentitySetupCoreTemplate',
26-
path: 'src/templates/shared/identity-setup-azure-devops-core.md',
27-
},
2824
{
2925
exportName: 'githubActionsIdentityGuideTemplate',
3026
path: 'src/templates/identity/identity-guide-github-actions.md',

src/cli/init-command.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -83,18 +83,18 @@ export function createInitCommand(): Command {
8383
generatedFiles.directories.forEach((dir) => logger.info(` - ${dir.startsWith('./') ? dir : './' + dir}`));
8484

8585
// Determine which CI provider was actually used by checking generated files
86-
const isGitHub = allFiles.some((f) => f.includes('IDENTITY-SETUP-GITHUB.md'));
86+
const isGitHub = allFiles.some((f) => f.includes('APIOPS-WORKFLOW-IDENTITY-SETUP.md'));
8787

8888
logger.info('\nNext steps:');
8989
logger.info(' 1. Review and customize the generated configuration files');
9090
logger.info(' 2. Commit the generated files to your repository');
9191
logger.info(' 3. Set up CI/CD identity authentication:');
9292
if (isGitHub) {
93-
logger.info(' - Follow ./IDENTITY-SETUP-GITHUB.md for manual setup, OR');
94-
logger.info(' - Open ./.github/prompts/apiops-setup-identity.prompt.md with GitHub Copilot for guided setup');
93+
logger.info(' - Follow APIOPS-WORKFLOW-IDENTITY-SETUP.md for manual setup, OR');
94+
logger.info(' - Use github/prompts/apiops-setup-workflow-identity.prompt.md prompt file with GitHub Copilot for guided setup');
9595
} else {
96-
logger.info(' - Follow ./IDENTITY-SETUP-AZDO.md for manual setup, OR');
97-
logger.info(' - Open ./.github/prompts/apiops-setup-identity.prompt.md with GitHub Copilot for guided setup');
96+
logger.info(' - Follow ./APIOPS-PIPELINE-IDENTITY-SETUP.md for manual setup, OR');
97+
logger.info(' - Open ./.github/prompts/apiops-setup-pipeline-identity.prompt.md with GitHub Copilot for guided setup');
9898
}
9999
logger.info('');
100100
} catch (error) {

src/services/identity-guide-service.ts

Lines changed: 7 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -2,76 +2,26 @@
22
// Licensed under the MIT license.
33
/**
44
* Identity setup guide generator
5-
* Step-by-step instructions for service principal, RBAC, federated credentials,
6-
* pipeline secrets/service connections. Optional az CLI automation per FR-021.
5+
* Returns the static manual guide content for the selected CI provider.
76
*/
87

98
import {
10-
azureDevOpsIdentitySetupCoreTemplate,
119
azureDevOpsIdentityGuideTemplate,
1210
githubActionsIdentityGuideTemplate,
1311
} from '../templates/generated/embedded-markdown.js';
14-
import { renderTemplate } from '../lib/render-template.js';
1512

1613
export interface IdentityGuideService {
17-
generateGitHubActionsGuide(
18-
subscriptionId: string,
19-
resourceGroup: string,
20-
environments: string[]
21-
): string;
22-
23-
generateAzureDevOpsGuide(
24-
environments: string[]
25-
): string;
14+
generateGitHubActionsGuide(): string;
15+
generateAzureDevOpsGuide(): string;
2616
}
2717

2818
class IdentityGuideServiceImpl implements IdentityGuideService {
29-
generateGitHubActionsGuide(
30-
subscriptionId: string,
31-
resourceGroup: string,
32-
environments: string[]
33-
): string {
34-
const federatedCredentialsPerEnvironment = environments.map((env) => `az ad app federated-credential create \\
35-
--id "$APP_ID" \\
36-
--parameters '{
37-
"name": "github-env-${env}",
38-
"issuer": "https://token.actions.githubusercontent.com",
39-
"subject": "repo:'"$GITHUB_ORG"'/'"$GITHUB_REPO"':environment:${env}",
40-
"audiences": ["api://AzureADTokenExchange"]
41-
}'`).join('\n\n');
42-
43-
const environmentSecrets = environments.map((env) => `
44-
**For ${env} environment:**
45-
- \`APIM_RESOURCE_GROUP_${env.toUpperCase()}\`: Resource group for ${env}
46-
- \`APIM_SERVICE_NAME_${env.toUpperCase()}\`: APIM service name for ${env}
47-
`).join('\n');
48-
49-
return renderTemplate(githubActionsIdentityGuideTemplate, {
50-
SUBSCRIPTION_ID: subscriptionId,
51-
RESOURCE_GROUP: resourceGroup,
52-
FEDERATED_CREDENTIALS_PER_ENV: federatedCredentialsPerEnvironment,
53-
ENVIRONMENT_SECRETS: environmentSecrets,
54-
});
19+
generateGitHubActionsGuide(): string {
20+
return githubActionsIdentityGuideTemplate;
5521
}
5622

57-
generateAzureDevOpsGuide(
58-
environments: string[]
59-
): string {
60-
const environmentsArrayPowerShell = environments
61-
.map((environment) => `"${environment}"`)
62-
.join(', ');
63-
const environmentsArrayBash = environments
64-
.map((environment) => `"${environment}"`)
65-
.join(' ');
66-
67-
const coreSteps = renderTemplate(azureDevOpsIdentitySetupCoreTemplate, {
68-
ENVIRONMENTS_ARRAY_POWERSHELL: environmentsArrayPowerShell,
69-
ENVIRONMENTS_ARRAY_BASH: environmentsArrayBash,
70-
});
71-
72-
return renderTemplate(azureDevOpsIdentityGuideTemplate, {
73-
AZURE_DEVOPS_CORE_STEPS: coreSteps,
74-
});
23+
generateAzureDevOpsGuide(): string {
24+
return azureDevOpsIdentityGuideTemplate;
7525
}
7626
}
7727

0 commit comments

Comments
 (0)