Skip to content

docs: Document Azure Foundry OpenAI v1 BYOK support #38641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 3 commits into from
Jun 11, 2026
+43 −1
Merged

docs: Document Azure Foundry OpenAI v1 BYOK support #38641

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
53fd8c9
Document Azure Foundry OpenAI v1 BYOK support
Copilot Jun 11, 2026
16e24e4
Remove AOAI smoke test docs link
Copilot Jun 11, 2026
5d8176d
docs: id-token when using github oidc auth
zarenner Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion docs/src/content/docs/reference/engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ Set `COPILOT_PROVIDER_BASE_URL` in `engine.env` to activate BYOK mode. The crede

| Variable | Required | Description |
|---|---|---|
| `COPILOT_PROVIDER_BASE_URL` | ✅ for BYOK | Base URL of the external provider (e.g. `https://api.openai.com/v1`) |
| `COPILOT_PROVIDER_BASE_URL` | ✅ for BYOK | Base URL of the external provider (e.g. `https://api.openai.com/v1` or `https://RESOURCE.openai.azure.com/openai/v1` for Azure Foundry OpenAI) |
| `COPILOT_MODEL` | ✅ for BYOK | Model to use (e.g. `claude-sonnet-4`, `gpt-4o`); required by most providers |
| `COPILOT_PROVIDER_API_KEY` | Optional | API key for cloud providers (OpenAI, Anthropic, etc.); not needed for local providers |
| `COPILOT_PROVIDER_BEARER_TOKEN` | Optional | Bearer token alternative to `COPILOT_PROVIDER_API_KEY`; takes precedence when set |
Expand Down Expand Up @@ -216,6 +216,50 @@ network:
> [!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

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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)

@zarenner zarenner Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot I believe new name is actually "Microsoft Foundry". Change wording to Azure OpenAI in Microsoft Foundry


Azure Foundry OpenAI supports the newer OpenAI v1 URL style. Set
`COPILOT_PROVIDER_BASE_URL` to the resource endpoint with the `/openai/v1`
path, then choose one authentication method:

```yaml wrap
engine:
id: copilot
model: o4-mini-aw
Comment thread
zarenner marked this conversation as resolved.

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-aw at the engine level is equivalent to COPILOT_MODEL: o4-mini-aw in env:. Either form satisfies the BYOK requirement; you do not need both.

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 label

And add a note: "Replace with the model label that matches your Azure deployment name (see COPILOT_PROVIDER_MODEL_ID if they differ)."

env:
COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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: responses

This 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.

@zarenner zarenner Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot add # COPILOT_PROVIDER_TYPE defaults to "openai" — correct for the v1 URL shape comment

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: responses

Or 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."

COPILOT_PROVIDER_API_KEY: ${{ secrets.FOUNDRY_API_KEY }}
COPILOT_PROVIDER_WIRE_API: responses
Comment thread
zarenner marked this conversation as resolved.

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


network:
allowed:
- defaults
- RESOURCE.openai.azure.com
```

For Entra authentication, omit `COPILOT_PROVIDER_API_KEY` and configure
GitHub OIDC in `engine.auth`:

```yaml wrap
engine:
id: copilot
model: o4-mini-aw
auth:

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.com

This is enforced by validateOIDCPermissions in permissions_compiler_validator.go:176–195.

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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: responses

These map to AWF_AUTH_AZURE_* env vars consumed by the AWF API proxy sidecar (see applyEngineAuthEnv in engine.go:592-630).

type: github-oidc

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.

@zarenner zarenner Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot proposed suggestion looks good, add.

env:
COPILOT_PROVIDER_BASE_URL: https://RESOURCE.openai.azure.com/openai/v1
COPILOT_PROVIDER_WIRE_API: responses

network:
allowed:
- defaults
- RESOURCE.openai.azure.com
```
Comment thread
Copilot marked this conversation as resolved.
Outdated

See the
Comment thread
zarenner marked this conversation as resolved.
Outdated
[Azure Foundry OpenAI API key smoke test](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-aoai-apikey.lock.yml)
for a working workflow run.

### Engine Command-Line Arguments

All engines support custom command-line arguments through the `args` field, injected before the prompt:
Expand Down
Loading