Skip to content

Commit 91ece89

Browse files
EMaherEMaher
committed
docs: add prompt files documentation
Describes available prompt files, how to download them individually (bash and PowerShell), and how to use them in VS Code and GitHub Copilot CLI.
1 parent 0720b0d commit 91ece89

1 file changed

Lines changed: 98 additions & 0 deletions

File tree

‎docs/guides/prompt-files.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
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. |
14+
| `apiops-configure-overrides.prompt.md` | Guides Copilot through creating environment override files (`configuration.<env>.yaml`) for promoting APIs across environments. |
15+
| `apiops-setup-workflow-identity.prompt.md` | Walks through setting up Azure identity (app registration, federated credentials, RBAC) for GitHub Actions or Azure DevOps CI/CD pipelines. |
16+
17+
## Getting prompt files
18+
19+
### Via `apiops init` (recommended)
20+
21+
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/`.
22+
23+
### Download individually
24+
25+
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.
26+
27+
#### Bash
28+
29+
```bash
30+
# Create the prompts directory
31+
mkdir -p .github/prompts
32+
33+
# Download prompt files
34+
curl -sL "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/configure-filter-prompt.md" \
35+
-o ".github/prompts/apiops-configure-filter.prompt.md"
36+
37+
curl -sL "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/configure-overrides-prompt.md" \
38+
-o ".github/prompts/apiops-configure-overrides.prompt.md"
39+
40+
# For GitHub Actions identity setup:
41+
curl -sL "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/identity-setup-prompt-github-actions.md" \
42+
-o ".github/prompts/apiops-setup-workflow-identity.prompt.md"
43+
44+
# For Azure DevOps identity setup:
45+
curl -sL "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/identity-setup-prompt-azure-devops.md" \
46+
-o ".github/prompts/apiops-setup-workflow-identity.prompt.md"
47+
```
48+
49+
#### PowerShell
50+
51+
```powershell
52+
# Create the prompts directory
53+
New-Item -ItemType Directory -Path ".github/prompts" -Force
54+
55+
# Download prompt files
56+
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/configure-filter-prompt.md" `
57+
-OutFile ".github/prompts/apiops-configure-filter.prompt.md"
58+
59+
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/configure-overrides-prompt.md" `
60+
-OutFile ".github/prompts/apiops-configure-overrides.prompt.md"
61+
62+
# For GitHub Actions identity setup:
63+
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/identity-setup-prompt-github-actions.md" `
64+
-OutFile ".github/prompts/apiops-setup-workflow-identity.prompt.md"
65+
66+
# For Azure DevOps identity setup:
67+
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Azure/apiops-cli/main/src/templates/copilot/identity-setup-prompt-azure-devops.md" `
68+
-OutFile ".github/prompts/apiops-setup-workflow-identity.prompt.md"
69+
```
70+
71+
## Using prompt files
72+
73+
### In VS Code
74+
75+
1. Open the prompt file (e.g., `.github/prompts/apiops-configure-filter.prompt.md`) in VS Code.
76+
2. Open the Copilot Chat panel and type `#` followed by the prompt file name, or use the **Attach Context** button to select it.
77+
3. Ask Copilot to help you complete the task described in the prompt.
78+
79+
For more details on using prompt files in VS Code, see the [VS Code documentation on reusable prompt files](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-prompt-files-experimental).
80+
81+
### In GitHub Copilot CLI
82+
83+
You can reference prompt files when using [GitHub Copilot in the CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli):
84+
85+
```bash
86+
# Ask Copilot CLI to use a prompt file as context
87+
gh copilot suggest --file .github/prompts/apiops-configure-filter.prompt.md "help me configure extraction filters"
88+
```
89+
90+
For more details, see the [GitHub Copilot in the CLI documentation](https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli).
91+
92+
## Further reading
93+
94+
- [VS Code: Reusable prompt files](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-prompt-files-experimental)
95+
- [GitHub Copilot in the CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli)
96+
- [APIOps `init` command reference](../commands/init.md)
97+
- [Filtering resources guide](./filtering-resources.md)
98+
- [Environment overrides guide](./environment-overrides.md)

0 commit comments

Comments
 (0)