diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index 6dc341450c..ac9fb409b8 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -32,6 +32,7 @@ engine: command: /usr/local/bin/copilot # custom executable path args: ["--add-dir", "/workspace"] # custom CLI arguments agent: agent-id # custom agent file identifier + api-target: api.acme.ghe.com # custom API endpoint hostname (GHEC/GHES) ``` ### Pinning a Specific Engine Version @@ -91,7 +92,52 @@ engine: Environment variables can also be defined at workflow, job, step, and other scopes. See [Environment Variables](/gh-aw/reference/environment-variables/) for complete documentation on precedence and all 13 env scopes. -#### Custom API Endpoints +### Enterprise API Endpoint (`api-target`) + +The `api-target` field specifies a custom API endpoint hostname for the agentic engine. Use this when running workflows against GitHub Enterprise Cloud (GHEC), GitHub Enterprise Server (GHES), or any custom AI endpoint. + +```yaml wrap +engine: + id: copilot + api-target: api.acme.ghe.com +network: + allowed: + - defaults + - acme.ghe.com + - api.acme.ghe.com +``` + +The value must be a hostname only — no protocol or path (e.g., `api.acme.ghe.com`, not `https://api.acme.ghe.com/v1`). The field works with any engine. + +**GHEC example** — specify your tenant-specific Copilot endpoint: + +```yaml wrap +engine: + id: copilot + api-target: api.acme.ghe.com +network: + allowed: + - defaults + - acme.ghe.com + - api.acme.ghe.com +``` + +**GHES example** — use the enterprise Copilot endpoint: + +```yaml wrap +engine: + id: copilot + api-target: api.enterprise.githubcopilot.com +network: + allowed: + - defaults + - github.company.com + - api.enterprise.githubcopilot.com +``` + +The specified hostname must also be listed in `network.allowed` for the firewall to permit outbound requests. + +#### Custom API Endpoints via Environment Variables Two environment variables receive special treatment when set in `engine.env`: `OPENAI_BASE_URL` (for `codex`) and `ANTHROPIC_BASE_URL` (for `claude`). When either is present, the AWF sandbox proxy automatically routes API calls to the specified host instead of the default `api.openai.com` or `api.anthropic.com`. Credential isolation and firewall enforcement remain active. diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md index f90cb90507..7228eb7445 100644 --- a/docs/src/content/docs/reference/frontmatter-full.md +++ b/docs/src/content/docs/reference/frontmatter-full.md @@ -1421,6 +1421,13 @@ engine: # (optional) agent: "example-value" + # Custom API endpoint hostname for the agentic engine. Used for GitHub Enterprise + # Cloud (GHEC), GitHub Enterprise Server (GHES), or custom AI endpoints. + # Accepts a hostname only (no protocol or path). + # Examples: "api.acme.ghe.com" (GHEC), "api.enterprise.githubcopilot.com" (GHES) + # (optional) + api-target: "example-value" + # Optional array of command-line arguments to pass to the AI engine CLI. These # arguments are injected after all other args but before the prompt. # (optional)