GitHub Copilot SDK on Azure
Codebase Detection — MANDATORY FIRST CHECK
⚠️ CRITICAL: This check MUST run before ANY other skill (azure-prepare, azure-deploy, etc.) when an existing codebase is present.
Detection procedure (run IMMEDIATELY for any build/modify/add-feature/prepare prompt):
- Read
package.jsonin the workspace root (and any*/package.jsonone level deep) - Check if
@github/copilot-sdkorcopilot-sdkappears inname,dependencies, ordevDependencies - If NOT found in package.json, scan
.tsand.jsfiles forCopilotClientorcreateSession - If ANY marker is found → invoke this skill as the entry point. Do not route directly to azure-prepare or azure-deploy — this skill orchestrates them as sub-skills.
| Marker | Where to check |
|---|---|
@github/copilot-sdk | package.json dependencies or devDependencies |
copilot-sdk | package.json name or dependencies |
CopilotClient | Source files (.ts, .js) |
createSession + sendAndWait | Source files (.ts, .js) |
Generic prompts that MUST trigger this skill when markers are detected:
| Prompt pattern (no "copilot" keyword) | Why this skill |
|---|---|
| "Build this app" / "Prepare this app for Azure" | Codebase contains @github/copilot-sdk - needs SDK-aware scaffolding |
| "Add a new feature to this app" | Requires SDK-aware implementation patterns |
| "Update this app" / "Modify this app" | Must preserve SDK integration patterns |
⚠️ Warning: ANY build, modify, add-feature, or prepare prompt targeting an existing codebase MUST route to this skill when codebase contains
@github/copilot-sdk, even if the prompt does not mention "copilot". This skill then orchestrates azure-prepare and azure-deploy as sub-skills.
⚠️ Yield to azure-deploy: When the codebase already has
.azure/deployment-plan.mdand the user wants to deploy (not modify or add features), route to azure-deploy instead. This skill handles preparation; azure-deploy handles execution.
Step 1: Route
| User wants | Action |
|---|---|
| Build new (empty project) | Step 2A (scaffold) |
| Add new SDK service to existing repo | Step 2B (scaffold alongside) |
| Deploy existing SDK app to Azure | Step 2C (add infra to existing SDK app) |
| Modify/add features to existing SDK app | Use codebase context + SDK references to implement |
| Add SDK to existing app code | Integrate SDK |
| Use Azure/own model | Step 3 (BYOM config) |
Step 2A: Scaffold New (Greenfield)
azd init --template azure-samples/copilot-sdk-service
Template includes API (Express/TS) + Web UI (React/Vite) + infra (Bicep) + Dockerfiles + token scripts — do NOT recreate. See SDK ref.
Step 2B: Add SDK Service to Existing Repo
User has existing code and wants a new Copilot SDK service alongside it. Scaffold template to a temp dir, copy the API service + infra into the user's repo, adapt azure.yaml to include both existing and new services. See deploy existing ref.
Step 2C: Deploy Existing SDK App
User already has a working Copilot SDK app and needs Azure infra. See deploy existing ref.
Step 3: Model Configuration
Three model paths (layers on top of 2A/2B):
| Path | Config |
|---|---|
| GitHub default | No model param — SDK picks default |
| GitHub specific | model: "<name>" — use listModels() to discover |
| Azure BYOM | model + provider with bearerToken via DefaultAzureCredential |
⚠️ BYOM Auth — MANDATORY: Azure BYOM configurations MUST use
DefaultAzureCredential(local dev) orManagedIdentityCredential(production) to obtain abearerToken. The ONLY supported auth pattern isbearerTokenin the provider config. See auth-best-practices.md for the credential pattern and model config ref for the full BYOM code example.
See model config ref.
Step 4: Deploy
Invoke azure-prepare (skip its Step 0 routing — scaffolding is done) → azure-validate → azure-deploy in order.
Rules
- Read
AGENTS.mdin user's repo before changes - Docker required (
docker info) - BYOM auth: ONLY
bearerTokenviaDefaultAzureCredentialorManagedIdentityCredential— no other auth pattern is supported
