From 72d523dd3896a60d357acb5ad02fe4a085c191fe Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 13 Mar 2026 04:21:40 +0000
Subject: [PATCH] docs: document engine api-target field for enterprise API
 endpoints

Add documentation for the new `api-target` field in engine configuration
(introduced in #20730), which allows workflows to target custom API
endpoints for GHEC, GHES, and custom AI providers.

- engines.md: add api-target to the extended config example, and add
  a new "Enterprise API Endpoint (api-target)" subsection with GHEC
  and GHES usage examples
- frontmatter-full.md: add api-target field entry in the engine block

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/src/content/docs/reference/engines.md    | 48 ++++++++++++++++++-
 .../docs/reference/frontmatter-full.md        |  7 +++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 6dc341450ca..ac9fb409b8c 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 f90cb90507b..7228eb74452 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)