diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index d8c6fa1333d..5d26112eae6 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -318,6 +318,7 @@ export default defineConfig({ { label: 'Upgrading Workflows', link: '/guides/upgrading/' }, { label: 'Using MCPs', link: '/guides/mcps/' }, { label: 'Network Configuration', link: '/guides/network-configuration/' }, + { label: 'Azure OpenAI BYOK', link: '/guides/azure-openai-byok/' }, { label: 'ARC DinD for Copilot Coding Agent', link: '/guides/arc-dind-copilot-agent/' }, { label: 'OpenTelemetry', link: '/guides/open-telemetry/' }, { label: 'GitHub Actions Primer', link: '/guides/github-actions-primer/' }, diff --git a/docs/src/content/docs/guides/azure-openai-byok.md b/docs/src/content/docs/guides/azure-openai-byok.md new file mode 100644 index 00000000000..4a528c70449 --- /dev/null +++ b/docs/src/content/docs/guides/azure-openai-byok.md @@ -0,0 +1,162 @@ +--- +title: How to use Azure OpenAI with Copilot BYOK +description: Configure GitHub Agentic Workflows to route Copilot through Azure OpenAI using API keys or Microsoft Entra authentication. +sidebar: + order: 325 +--- + +Azure OpenAI is supported in Copilot Bring Your Own Key (BYOK) mode. Use the +Azure OpenAI resource's OpenAI v1 endpoint, put provider credentials in +`engine.env`, and choose the wire model deliberately when Azure deployment names +do not match Azure model IDs. + +## Use the Azure OpenAI v1 endpoint + +Set `COPILOT_PROVIDER_BASE_URL` to the Azure resource endpoint with the +`/openai/v1` suffix: + +```aw wrap +engine: + id: copilot + model: gpt-5.4-2026-03-05 + env: + COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 +``` + +Do not use the older `/openai/v1-preview` path unless the Azure resource +explicitly exposes it. The repository smoke workflows +`smoke-copilot-aoai-apikey.md` and `smoke-copilot-aoai-entra.md` both use the +v1 endpoint. + +## Choose the model name and deployment name + +`engine.model` (compiled to `COPILOT_MODEL`) should name the Azure model ID that +the provider exposes from `GET /openai/v1/models`. For versioned GPT-5 models, +that is often a fully qualified name such as `gpt-5.4-2026-03-05`. + +If the Azure deployment name is different, set `COPILOT_PROVIDER_MODEL_ID` to +the deployment name that Azure expects on the request body: + +```aw wrap +engine: + id: copilot + model: gpt-5.4-2026-03-05 + env: + COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 + COPILOT_PROVIDER_MODEL_ID: gpt-5.4 +``` + +This keeps the AWF proxy and Copilot CLI aligned on the selected model while +still sending the Azure deployment name upstream. + +## Configure API-key authentication + +```aw wrap +engine: + id: copilot + model: gpt-5.4-2026-03-05 + env: + COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 + COPILOT_PROVIDER_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} + COPILOT_PROVIDER_MODEL_ID: gpt-5.4 + COPILOT_PROVIDER_WIRE_API: responses + +network: + allowed: + - defaults + - RESOURCE.openai.azure.com +``` + +`COPILOT_PROVIDER_WIRE_API: responses` is required for GPT-5 and o-series +models — see [Use the `responses` wire +API](#use-the-responses-wire-api-for-gpt-5-and-o-series-models) below for +details. + +> [!IMPORTANT] +> Put Azure BYOK credentials in `engine.env`, not in top-level `secrets:`. The +> BYOK proxy only receives provider credentials from the engine environment. + +## Configure Microsoft Entra authentication + +Use GitHub OIDC when the Azure resource trusts a federated identity: + +```aw wrap +permissions: + id-token: write + +engine: + id: copilot + model: gpt-5.4-2026-03-05 + auth: + type: github-oidc + provider: azure + azure-tenant-id: + azure-client-id: + env: + COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 + COPILOT_PROVIDER_MODEL_ID: gpt-5.4 + COPILOT_PROVIDER_WIRE_API: responses + +network: + allowed: + - defaults + - RESOURCE.openai.azure.com + - login.microsoftonline.com +``` + +`COPILOT_PROVIDER_WIRE_API: responses` is required for GPT-5 and o-series +models — see [Use the `responses` wire +API](#use-the-responses-wire-api-for-gpt-5-and-o-series-models) below for +details. + +## Use the `responses` wire API for GPT-5 and o-series models + +The Copilot CLI defaults custom providers to the legacy `completions` wire API. +Azure GPT-5 and o-series deployments typically require the newer `responses` +wire API instead: + +```aw wrap +engine: + env: + COPILOT_PROVIDER_WIRE_API: responses +``` + +The repository smoke workflows `smoke-copilot-aoai-apikey.md` and +`smoke-copilot-aoai-entra.md` both use this setting. + +## Troubleshooting + +If Azure works with direct `curl` requests but the AWF proxy returns +`model not found`, check these items first: + +- Verify that `engine.model` matches a model returned by + `GET /openai/v1/models`. +- If Azure requires a different deployment name on the wire, set + `COPILOT_PROVIDER_MODEL_ID` to that deployment name. +- Keep `COPILOT_PROVIDER_BASE_URL` on the `/openai/v1` endpoint. +- Set `COPILOT_PROVIDER_WIRE_API: responses` for GPT-5 and o-series models. + +If the proxy still rewrites the deployment name and Azure returns HTTP 404, +disable AWF model fallback for that workflow: + +```aw wrap +sandbox: + agent: + id: awf + model-fallback: false +``` + +## Recompile after workflow edits + +Azure BYOK settings live in workflow frontmatter. All workflow edits require a +recompile: + +```bash +gh aw compile .github/workflows/my-workflow.md --watch +``` + +## Related documentation + +- [AI Engines Reference](/gh-aw/reference/engines/#copilot-bring-your-own-key-byok-mode) +- [Network Configuration Guide](/gh-aw/guides/network-configuration/) +- [Sandbox Reference](/gh-aw/reference/sandbox/) diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index 3407f16d98e..348f36911d1 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -237,6 +237,11 @@ network: - RESOURCE.openai.azure.com ``` +When the Azure deployment name differs from the Azure model ID, keep +`engine.model` on the model ID that Azure exposes from `/openai/v1/models` and +set `COPILOT_PROVIDER_MODEL_ID` to the deployment name that Azure expects on +the wire. + For Entra authentication, omit `COPILOT_PROVIDER_API_KEY` and configure GitHub OIDC in `engine.auth`: @@ -257,6 +262,11 @@ network: allowed: - defaults - RESOURCE.openai.azure.com +``` + +See [How to use Azure OpenAI with Copilot BYOK](/gh-aw/guides/azure-openai-byok/) +for deployment-name mapping, `responses` API guidance for GPT-5 and o-series +models, and Azure-specific troubleshooting. ### Engine Command-Line Arguments