feat(cli): auto-populate GHES firewall domains from engine.api-target (#1306)

* Initial plan

* feat(cli): add GHES domain auto-population from engine.api-target

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* feat(cli): add GHES auto-populate integration test and docs

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

---------

Co-authored-by: anthropic-code-agent[bot] <242468646+Claude@users.noreply.github.com>
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Author: Claude

docs/enterprise-configuration.md

@@ -124,6 +124,37 @@ When `GITHUB_SERVER_URL` is set to a non-github.com, non-ghe.com domain, AWF aut
 # AWF automatically uses: api.enterprise.githubcopilot.com
 ```
 
+### Auto-Population for GitHub Agentic Workflows
+
+**New in v0.24.0:** When running agentic workflows with `engine.api-target` set (via the `ENGINE_API_TARGET` environment variable), AWF automatically adds GHES domains to the firewall allowlist. You no longer need to manually specify these domains in `--allow-domains` or `GH_AW_ALLOWED_DOMAINS`.
+
+**Auto-added domains:**
+- The GHES base domain (e.g., `github.mycompany.com` from `https://api.github.mycompany.com`)
+- The GHES API subdomain (e.g., `api.github.mycompany.com`)
+- Copilot API domains required even on GHES:
+  - `api.githubcopilot.com`
+  - `api.enterprise.githubcopilot.com`
+  - `telemetry.enterprise.githubcopilot.com`
+
+**Example:**
+```bash
+# When ENGINE_API_TARGET=https://api.github.mycompany.com
+# AWF automatically adds these to the allowlist:
+# - github.mycompany.com
+# - api.github.mycompany.com
+# - api.githubcopilot.com
+# - api.enterprise.githubcopilot.com
+# - telemetry.enterprise.githubcopilot.com
+
+# Before (manual configuration):
+export ENGINE_API_TARGET="https://api.github.mycompany.com"
+export GH_AW_ALLOWED_DOMAINS="github.mycompany.com,api.github.mycompany.com,api.githubcopilot.com,api.enterprise.githubcopilot.com,telemetry.enterprise.githubcopilot.com"
+
+# After (automatic):
+export ENGINE_API_TARGET="https://api.github.mycompany.com"
+# No need to set GH_AW_ALLOWED_DOMAINS - domains are auto-populated!
+```
+
 ### Required Domains for GHES
 
 ```bash

src/cli.test.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, parseDnsOverHttps, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, hasRateLimitOptions, collectRulesetFile, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, DEFAULT_COPILOT_API_TARGET, emitApiProxyTargetWarnings, formatItem, program, parseAgentTimeout, applyAgentTimeout, handlePredownloadAction, resolveApiTargetsToAllowedDomains } from './cli';
+import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, parseDnsOverHttps, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, hasRateLimitOptions, collectRulesetFile, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, DEFAULT_COPILOT_API_TARGET, emitApiProxyTargetWarnings, formatItem, program, parseAgentTimeout, applyAgentTimeout, handlePredownloadAction, resolveApiTargetsToAllowedDomains, extractGhesDomainsFromEngineApiTarget } from './cli';
 import { redactSecrets } from './redact-secrets';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -2175,4 +2175,87 @@ describe('cli', () => {
       expect(hasRateLimitOptions({ rateLimit: true })).toBe(false);
     });
   });
+
+  describe('extractGhesDomainsFromEngineApiTarget', () => {
+    it('should return empty array when ENGINE_API_TARGET is not set', () => {
+      const domains = extractGhesDomainsFromEngineApiTarget({});
+      expect(domains).toEqual([]);
+    });
+
+    it('should extract GHES domains from api.github.* format', () => {
+      const env = { ENGINE_API_TARGET: 'https://api.github.mycompany.com' };
+      const domains = extractGhesDomainsFromEngineApiTarget(env);
+      expect(domains).toContain('github.mycompany.com');
+      expect(domains).toContain('api.github.mycompany.com');
+      expect(domains).toContain('api.githubcopilot.com');
+      expect(domains).toContain('api.enterprise.githubcopilot.com');
+      expect(domains).toContain('telemetry.enterprise.githubcopilot.com');
+    });
+
+    it('should handle non-api.* hostnames', () => {
+      const env = { ENGINE_API_TARGET: 'https://github.mycompany.com' };
+      const domains = extractGhesDomainsFromEngineApiTarget(env);
+      expect(domains).toContain('github.mycompany.com');
+      expect(domains).toContain('api.githubcopilot.com');
+      expect(domains).toContain('api.enterprise.githubcopilot.com');
+      expect(domains).toContain('telemetry.enterprise.githubcopilot.com');
+    });
+
+    it('should handle invalid URL gracefully', () => {
+      const env = { ENGINE_API_TARGET: 'not-a-valid-url' };
+      const domains = extractGhesDomainsFromEngineApiTarget(env);
+      expect(domains).toEqual([]);
+    });
+
+    it('should always include Copilot API domains for GHES', () => {
+      const env = { ENGINE_API_TARGET: 'https://api.github.enterprise.local' };
+      const domains = extractGhesDomainsFromEngineApiTarget(env);
+      expect(domains).toContain('api.githubcopilot.com');
+      expect(domains).toContain('api.enterprise.githubcopilot.com');
+      expect(domains).toContain('telemetry.enterprise.githubcopilot.com');
+    });
+  });
+
+  describe('resolveApiTargetsToAllowedDomains with GHES', () => {
+    it('should auto-add GHES domains when ENGINE_API_TARGET is set', () => {
+      const domains: string[] = ['github.com'];
+      const env = { ENGINE_API_TARGET: 'https://api.github.mycompany.com' };
+      resolveApiTargetsToAllowedDomains({}, domains, env);
+      expect(domains).toContain('github.mycompany.com');
+      expect(domains).toContain('api.github.mycompany.com');
+      expect(domains).toContain('api.githubcopilot.com');
+      expect(domains).toContain('api.enterprise.githubcopilot.com');
+      expect(domains).toContain('telemetry.enterprise.githubcopilot.com');
+    });
+
+    it('should not duplicate GHES domains if already in allowlist', () => {
+      const domains: string[] = ['github.mycompany.com', 'api.githubcopilot.com'];
+      const env = { ENGINE_API_TARGET: 'https://api.github.mycompany.com' };
+      resolveApiTargetsToAllowedDomains({}, domains, env);
+      const ghesCount = domains.filter(d => d === 'github.mycompany.com').length;
+      const copilotCount = domains.filter(d => d === 'api.githubcopilot.com').length;
+      expect(ghesCount).toBe(1);
+      expect(copilotCount).toBe(1);
+    });
+
+    it('should combine GHES domains with API target domains', () => {
+      const domains: string[] = [];
+      const env = { ENGINE_API_TARGET: 'https://api.github.mycompany.com' };
+      resolveApiTargetsToAllowedDomains(
+        { copilotApiTarget: 'custom.copilot.com' },
+        domains,
+        env
+      );
+      // GHES domains
+      expect(domains).toContain('github.mycompany.com');
+      expect(domains).toContain('api.github.mycompany.com');
+      // Copilot API domains
+      expect(domains).toContain('api.githubcopilot.com');
+      expect(domains).toContain('api.enterprise.githubcopilot.com');
+      expect(domains).toContain('telemetry.enterprise.githubcopilot.com');
+      // Custom API target
+      expect(domains).toContain('custom.copilot.com');
+      expect(domains).toContain('https://custom.copilot.com');
+    });
+  });
 });

src/cli.ts

@@ -378,6 +378,52 @@ export function emitApiProxyTargetWarnings(
   }
 }
 
+/**
+ * Extracts GHES API domains from engine.api-target environment variable.
+ * When engine.api-target is set (indicating GHES), returns the GHES hostname,
+ * API subdomain, and required Copilot API domains.
+ *
+ * @param env - Environment variables (defaults to process.env)
+ * @returns Array of domains to auto-add to allowlist, or empty array if not GHES
+ */
+export function extractGhesDomainsFromEngineApiTarget(
+  env: Record<string, string | undefined> = process.env
+): string[] {
+  const engineApiTarget = env['ENGINE_API_TARGET'];
+  if (!engineApiTarget) {
+    return [];
+  }
+
+  const domains: string[] = [];
+
+  try {
+    // Parse the engine.api-target URL (e.g., https://api.github.mycompany.com)
+    const url = new URL(engineApiTarget);
+    const hostname = url.hostname;
+
+    // Extract the base GHES domain from api.github.<ghes-domain>
+    // For example: api.github.mycompany.com → github.mycompany.com
+    if (hostname.startsWith('api.')) {
+      const baseDomain = hostname.substring(4); // Remove 'api.' prefix
+      domains.push(baseDomain);
+      domains.push(hostname); // Also add the api subdomain itself
+    } else {
+      // If it doesn't start with 'api.', just add the hostname
+      domains.push(hostname);
+    }
+
+    // Add Copilot API domains (needed even on GHES since Copilot models run in GitHub's cloud)
+    domains.push('api.githubcopilot.com');
+    domains.push('api.enterprise.githubcopilot.com');
+    domains.push('telemetry.enterprise.githubcopilot.com');
+  } catch {
+    // Invalid URL format - skip GHES domain extraction
+    return [];
+  }
+
+  return domains;
+}
+
 /**
  * Resolves API target values from CLI options and environment variables, and merges them
  * into the allowed domains list. Also ensures each target is present as an https:// URL.
@@ -417,6 +463,17 @@ export function resolveApiTargetsToAllowedDomains(
     apiTargets.push(env['ANTHROPIC_API_TARGET']);
   }
 
+  // Auto-populate GHES domains when engine.api-target is set
+  const ghesDomains = extractGhesDomainsFromEngineApiTarget(env);
+  if (ghesDomains.length > 0) {
+    for (const domain of ghesDomains) {
+      if (!allowedDomains.includes(domain)) {
+        allowedDomains.push(domain);
+      }
+    }
+    debug(`Auto-added GHES domains from engine.api-target: ${ghesDomains.join(', ')}`);
+  }
+
   // Merge raw target values into the allowedDomains list so that later
   // checks/logs about "no allowed domains" see the final, expanded allowlist.
   const normalizedApiTargets = apiTargets.filter((t) => typeof t === 'string' && t.trim().length > 0);