docs: Document Azure Foundry OpenAI v1 BYOK support#38641
Conversation
Co-authored-by: zarenner <13670625+zarenner@users.noreply.github.com>
Co-authored-by: zarenner <13670625+zarenner@users.noreply.github.com>
zarenner
changed the title
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #38641 does not have the 'implementation' label and has 0 new lines of code in business logic directories (≤100 threshold). This is a documentation-focused change. |
There was a problem hiding this comment.
Pull request overview
This PR updates the Copilot BYOK (Bring Your Own Key) documentation to explicitly include Azure Foundry OpenAI support using the newer OpenAI v1-style /openai/v1 base URL shape, and provides authentication examples for API key and GitHub OIDC (Entra) flows.
Changes:
- Expanded
COPILOT_PROVIDER_BASE_URLguidance to include the Azure Foundry OpenAI/openai/v1endpoint format. - Added a dedicated “Azure Foundry OpenAI” section with YAML examples for API key auth and Entra auth via
engine.auth.type: github-oidc.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/engines.md | Documents Azure Foundry OpenAI BYOK base URL format and provides API key + GitHub OIDC authentication examples. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 1
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The only changed file is docs/src/content/docs/reference/engines.md (documentation). Test Quality Sentinel skipped. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — the new section is well-structured and the two auth patterns are clearly separated, but there are a few terminology and completeness gaps worth addressing before this lands.
📋 Key Themes & Highlights
Key Themes
- Product naming: "Azure Foundry OpenAI" is not a standard Microsoft product name — consider "Azure AI Foundry" (portal) and/or "Azure OpenAI Service" (API surface) to match official docs.
COPILOT_PROVIDER_TYPEgap: The reference table documentsazureas a valid type, but the examples omitCOPILOT_PROVIDER_TYPEentirely. It is unclear whether the defaultopenaiis correct for the v1 URL shape or whetherazureis needed.model:vsCOPILOT_MODEL: The main BYOK example usesCOPILOT_MODELinenv:(marked ✅ required). The Azure Foundry examples useengine.modelat the top level. A clarification that these are equivalent (or a decision to standardize) would remove the inconsistency.COPILOT_PROVIDER_WIRE_API: responsesrationale: The reference table saysresponsesis for the "GPT-5 series", but the model here iso4-mini-aw. A brief comment explaining whyresponsesis used (e.g., Azure Foundry only supports the Responses API) would prevent copy-paste errors on other deployments.engine.authfirst use: The Entra example is the first mention ofengine.authin the file; a cross-reference to auth docs and a note about required Azure Federated Identity Credential setup would significantly reduce first-time user friction.
Positive Highlights
- ✅ Both YAML examples correctly include
network.allowedfor the Azure hostname — consistent with the sandbox security model. - ✅ The two auth paths (API key vs Entra OIDC) are cleanly separated with their own examples.
- ✅ The reference table update at line 188 proactively surfaces the Azure Foundry URL shape in the most-consulted part of the section.
- ✅
yaml wrapattribute used consistently for readability on long YAML blocks.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 246.4 AIC · ⌖ 26.3 AIC
| > [!NOTE] | ||
| > Credentials are kept out of the agent container — only a dummy API key activating the AWF BYOK detection path is visible to the agent process; the real credential is isolated in the AWF API proxy sidecar. See [AWF sandbox architecture](/gh-aw/reference/sandbox/). | ||
|
|
||
| #### Azure Foundry OpenAI |
There was a problem hiding this comment.
[/grill-with-docs] "Azure Foundry OpenAI" is not the official Microsoft product name — the studio is Azure AI Foundry and the API surface is the Azure OpenAI Service. Readers searching the official docs will not find "Azure Foundry OpenAI".
💡 Suggested heading and intro tweak
Consider:
#### Azure AI Foundry (Azure OpenAI Service)
Azure AI Foundry exposes models through the Azure OpenAI Service using the
newer OpenAI v1 URL style. Set `COPILOT_PROVIDER_BASE_URL` to your Foundry
project endpoint with the `/openai/v1` path, then choose an authentication method:
Using the canonical names avoids confusion when users cross-reference the [Azure AI Foundry docs]((learn.microsoft.com/redacted)
There was a problem hiding this comment.
@copilot I believe new name is actually "Microsoft Foundry". Change wording to Azure OpenAI in Microsoft Foundry
| id: copilot | ||
| model: o4-mini-aw | ||
| env: | ||
| COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 |
There was a problem hiding this comment.
[/grill-with-docs] The COPILOT_PROVIDER_TYPE variable is omitted from both examples. The reference table lists valid values as openai (default), azure, and anthropic. It is not clear whether Azure Foundry with a /openai/v1 URL works with the default openai type or requires azure.
💡 Suggested clarification
If the default openai type is correct for the v1 URL style (as the PR description implies), adding a comment would make this explicit:
COPILOT_PROVIDER_BASE_URL: (resource.openai.azure.com/redacted)
# COPILOT_PROVIDER_TYPE defaults to "openai" — correct for the v1 URL shape
COPILOT_PROVIDER_API_KEY: ${{ secrets.FOUNDRY_API_KEY }}
COPILOT_PROVIDER_WIRE_API: responsesThis is especially helpful because the existing docs already mention azure as a provider type, and users with prior Azure OpenAI experience may assume azure is needed.
There was a problem hiding this comment.
@copilot add # COPILOT_PROVIDER_TYPE defaults to "openai" — correct for the v1 URL shape comment
| id: copilot | ||
| model: o4-mini-aw | ||
| auth: | ||
| type: github-oidc |
There was a problem hiding this comment.
[/grill-with-docs] engine.auth.type: github-oidc is introduced here without a cross-reference to how it works or what Azure-side setup is required (Federated Identity Credential on the Managed Identity / App Registration). This is the first mention of engine.auth in the file.
💡 Suggested addition
A brief prerequisite note would make the example self-contained for users who are unfamiliar with OIDC federation:
> [!NOTE]
> Entra authentication requires a Federated Identity Credential configured on your Azure
> Managed Identity or App Registration. See the [GitHub OIDC authentication docs](/gh-aw/reference/auth/#github-oidc)
> and the [Azure workload identity federation guide]((learn.microsoft.com/redacted)Without this, users will hit a 401 from Azure without a clear debugging path.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Non-blocking observations on the Azure Foundry OpenAI docs
Three documentation consistency gaps worth addressing before or shortly after merge — none are blockers, but two of them could send users down the wrong path.
📋 Findings summary
-
COPILOT_PROVIDER_WIRE_API: responsescontradicts the existing table (line 232): the table currently saysresponsesis "for GPT-5 series", but both new examples use it witho4-mini-aw. Users reading the table first will assumecompletionsis correct for o4 models and misconfigure their workflow. The table description needs to be broadened to include Azure Foundry OpenAI (or o4 series). -
model:vsCOPILOT_MODELenv is ambiguous (line 228): the BYOK table marksCOPILOT_MODELas required, but the Azure examples use the engine-levelmodel:field. A clarifying note that they are equivalent would prevent confusion. -
COPILOT_PROVIDER_MODEL_IDis absent from the examples (line 230): the table explicitly notes this variable is for Azure deployment names that differ from the model label. Omitting it from examples means users with non-default deployment names will send the wrong model ID on the wire. A commented-out line or prose note would cover this.
🔎 Code quality review by PR Code Quality Reviewer · ⌖ 44.9 AIC
| env: | ||
| COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 | ||
| COPILOT_PROVIDER_API_KEY: ${{ secrets.FOUNDRY_API_KEY }} | ||
| COPILOT_PROVIDER_WIRE_API: responses |
There was a problem hiding this comment.
responses wire API contradicts the table description for o4-mini-aw: the existing COPILOT_PROVIDER_WIRE_API table row says responses is "for GPT-5 series", but both Azure examples here use it with o4-mini-aw (an o4 model). A reader following the table would assume completions is correct for o4 models and misconfigure their workflow.
💡 Suggested fix
Update the COPILOT_PROVIDER_WIRE_API table entry to clarify when responses is required beyond GPT-5, e.g.:
| `COPILOT_PROVIDER_WIRE_API` | Optional | Wire API variant: `completions` (default) or `responses` (required for GPT-5 series and Azure Foundry OpenAI) |
Alternatively, add a brief inline note here explaining why responses is needed for the AOAI v1 endpoint regardless of model series.
| ```yaml wrap | ||
| engine: | ||
| id: copilot | ||
| model: o4-mini-aw |
There was a problem hiding this comment.
model: field vs COPILOT_MODEL env variable is ambiguous for BYOK users: the BYOK table above marks COPILOT_MODEL as ✅ for BYOK (required), but both Azure examples use the engine-level model: field instead. A user following the table will add COPILOT_MODEL to env: and wonder whether model: is redundant, or vice versa.
💡 Suggested fix
Add a brief clarifying note in the BYOK section explaining that model: and COPILOT_MODEL env are equivalent — the engine-level model: field is the preferred form and sets the same value. For example:
Tip:
model: o4-mini-awat the engine level is equivalent toCOPILOT_MODEL: o4-mini-awinenv:. Either form satisfies the BYOK requirement; you do not need both.
| id: copilot | ||
| model: o4-mini-aw | ||
| env: | ||
| COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1 |
There was a problem hiding this comment.
Azure deployment names typically differ from model IDs — COPILOT_PROVIDER_MODEL_ID is missing from the example: the BYOK table documents COPILOT_PROVIDER_MODEL_ID specifically for this case ("Model ID sent on the wire when it differs from COPILOT_MODEL (e.g. an Azure deployment name)"), yet neither Azure example mentions it. If the AOAI deployment name differs from o4-mini-aw — which is the norm in Azure — the request will silently fail or hit the wrong deployment.
💡 Suggested fix
Add COPILOT_PROVIDER_MODEL_ID to the API-key example (and note it in the Entra example) so users know to set it when their Azure deployment name differs:
engine:
id: copilot
model: o4-mini-aw
env:
COPILOT_PROVIDER_BASE_URL: (resource.openai.azure.com/redacted)
COPILOT_PROVIDER_API_KEY: ${{ secrets.FOUNDRY_API_KEY }}
COPILOT_PROVIDER_MODEL_ID: your-deployment-name # set if deployment name ≠ model label
COPILOT_PROVIDER_WIRE_API: responsesOr at minimum add a prose note: "If your Azure deployment name differs from the model label, set COPILOT_PROVIDER_MODEL_ID to the deployment name."
| engine: | ||
| id: copilot | ||
| model: o4-mini-aw | ||
| auth: |
There was a problem hiding this comment.
This Entra example will fail to compile: the compiler (validateOIDCPermissions) hard-errors with "engine.auth.type: github-oidc requires permissions.id-token: write" whenever engine.auth.type: github-oidc is set and permissions.id-token: write is absent. The example has no permissions: block, so any user copying it verbatim gets a compilation failure.
💡 Suggested fix
Add a permissions block to the example:
permissions:
id-token: write
engine:
id: copilot
model: o4-mini-aw
auth:
type: github-oidc
env:
COPILOT_PROVIDER_BASE_URL: (resource.openai.azure.com/redacted)
COPILOT_PROVIDER_WIRE_API: responses
network:
allowed:
- defaults
- RESOURCE.openai.azure.comThis is enforced by validateOIDCPermissions in permissions_compiler_validator.go:176–195.
| engine: | ||
| id: copilot | ||
| model: o4-mini-aw | ||
| auth: |
There was a problem hiding this comment.
Entra example will fail at runtime — engine.auth is missing all Azure federation fields: engine.auth.type: github-oidc alone only sets AWF_AUTH_TYPE=github-oidc on the proxy sidecar. The AWF proxy also needs azure-tenant-id, azure-client-id, and azure-scope (mapped to AWF_AUTH_AZURE_TENANT_ID, AWF_AUTH_AZURE_CLIENT_ID, AWF_AUTH_AZURE_SCOPE) to exchange the GitHub OIDC token for an Azure credential. Without these, the token exchange will fail and the workflow will error at runtime.
💡 Suggested fix
Expand the auth: block with the required Azure WIF fields:
engine:
id: copilot
model: o4-mini-aw
auth:
type: github-oidc
audience: (cognitiveservices.azure.com/redacted)
azure-tenant-id: ${{ vars.AZURE_TENANT_ID }}
azure-client-id: ${{ vars.AZURE_CLIENT_ID }}
azure-scope: (cognitiveservices.azure.com/redacted)
env:
COPILOT_PROVIDER_BASE_URL: (resource.openai.azure.com/redacted)
COPILOT_PROVIDER_WIRE_API: responsesThese map to AWF_AUTH_AZURE_* env vars consumed by the AWF API proxy sidecar (see applyEngineAuthEnv in engine.go:592-630).
| ```yaml wrap | ||
| engine: | ||
| id: copilot | ||
| model: o4-mini-aw |
There was a problem hiding this comment.
o4-mini-aw is an internal team deployment alias, not a standard Azure model name — users who copy this will configure the wrong deployment: there is no public Azure OpenAI model named o4-mini-aw; this appears to be the AWF team's own deployment name. Real users create their own Azure deployments with their own names (e.g., o4-mini, my-reasoning-model). Copying this value verbatim will result in model-not-found or deployment errors.
💡 Suggested fix
Replace o4-mini-aw with a clearly generic placeholder, e.g.:
model: o4-mini # or your Azure deployment labelAnd add a note: "Replace with the model label that matches your Azure deployment name (see COPILOT_PROVIDER_MODEL_ID if they differ)."
|
@copilot review all comments and address unresolved review feedback, then re-request review after refreshing the branch if needed.
|
Azure Foundry OpenAI is supported through the newer OpenAI v1 URL shape for Copilot BYOK. Workflows can use either Foundry API key auth or Entra auth through GitHub OIDC.
Copilot BYOK reference
COPILOT_PROVIDER_BASE_URLtarget./openai/v1endpoint format.Authentication options
COPILOT_PROVIDER_API_KEY.engine.auth.type: github-oidc.