Skip to content

Commit 6de4fb6

Browse files
Claudelpcox
Claude
and
lpcox
committed
docs: add enterprise configuration guide for GHEC/GHES
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>
1 parent 7c9dc34 commit 6de4fb6

2 files changed

Lines changed: 354 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ The `--` separator divides firewall options from the command to run.
3333

3434
- [Quick start](docs/quickstart.md) — install, verify, and run your first command
3535
- [Usage guide](docs/usage.md) — CLI flags, domain allowlists, examples
36+
- [Enterprise configuration](docs/enterprise-configuration.md) — GitHub Enterprise Cloud and Server setup
3637
- [Chroot mode](docs/chroot-mode.md) — use host binaries with network isolation
3738
- [API proxy sidecar](docs/api-proxy-sidecar.md) — secure credential management for LLM APIs
3839
- [Authentication architecture](docs/authentication-architecture.md) — deep dive into token handling and credential isolation

‎docs/enterprise-configuration.md‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
# GitHub Enterprise Configuration
2+
3+
This guide explains how to configure AWF for GitHub Enterprise Cloud (GHEC) and GitHub Enterprise Server (GHES) customers.
4+
5+
## Overview
6+
7+
AWF automatically detects your GitHub environment and configures the appropriate API endpoints. The API proxy sidecar intelligently routes GitHub Copilot API traffic based on your `GITHUB_SERVER_URL` environment variable.
8+
9+
## GitHub Enterprise Cloud (*.ghe.com)
10+
11+
GitHub Enterprise Cloud customers use domains like `https://mycompany.ghe.com`. AWF automatically detects GHEC domains and routes traffic to the tenant-specific API endpoint.
12+
13+
### Automatic Configuration
14+
15+
When `GITHUB_SERVER_URL` is set to a `*.ghe.com` domain, AWF automatically derives the correct Copilot API endpoint:
16+
17+
```bash
18+
# Example: GITHUB_SERVER_URL=https://acme.ghe.com
19+
# AWF automatically uses: api.acme.ghe.com
20+
```
21+
22+
**How it works:**
23+
1. AWF reads `GITHUB_SERVER_URL` from your environment
24+
2. Detects that the hostname ends with `.ghe.com`
25+
3. Extracts the subdomain (e.g., `acme` from `acme.ghe.com`)
26+
4. Routes Copilot API traffic to `api.<subdomain>.ghe.com`
27+
28+
### Required Domains for GHEC
29+
30+
For GHEC environments, you need to whitelist your tenant-specific domains:
31+
32+
```bash
33+
export GITHUB_SERVER_URL="https://acme.ghe.com"
34+
export GITHUB_TOKEN="<your-copilot-cli-token>"
35+
36+
sudo -E awf \
37+
--allow-domains acme.ghe.com,api.acme.ghe.com,raw.githubusercontent.com \
38+
--enable-api-proxy \
39+
-- npx @github/copilot@latest --prompt "your prompt here"
40+
```
41+
42+
**Domain breakdown:**
43+
- `acme.ghe.com` - Your GHEC tenant domain (git operations, web UI)
44+
- `api.acme.ghe.com` - Your tenant-specific Copilot API endpoint (automatically routed by AWF)
45+
- `raw.githubusercontent.com` - Raw content access (if using GitHub MCP server)
46+
47+
### GitHub Actions (GHEC)
48+
49+
In GitHub Actions workflows running on GHEC, the `GITHUB_SERVER_URL` environment variable is automatically set by GitHub Actions. No additional configuration is needed:
50+
51+
```yaml
52+
jobs:
53+
test:
54+
runs-on: ubuntu-latest
55+
steps:
56+
- name: Setup awf
57+
uses: github/gh-aw-firewall@main
58+
59+
- name: Run Copilot with GHEC
60+
env:
61+
GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
62+
# GITHUB_SERVER_URL is automatically set by GitHub Actions
63+
run: |
64+
sudo -E awf \
65+
--allow-domains ${{ github.server_url_hostname }},api.${{ github.server_url_hostname }},raw.githubusercontent.com \
66+
--enable-api-proxy \
67+
-- npx @github/copilot@latest --prompt "generate tests"
68+
```
69+
70+
**Note:** Use `${{ github.server_url_hostname }}` to dynamically get your GHEC hostname (e.g., `acme.ghe.com`).
71+
72+
### MCP Server Configuration (GHEC)
73+
74+
When using GitHub MCP server with GHEC, ensure your MCP configuration uses the correct endpoint:
75+
76+
```json
77+
{
78+
"mcpServers": {
79+
"github": {
80+
"type": "local",
81+
"command": "docker",
82+
"args": [
83+
"run", "-i", "--rm",
84+
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
85+
"-e", "GITHUB_SERVER_URL",
86+
"ghcr.io/github/github-mcp-server:latest"
87+
],
88+
"tools": ["*"],
89+
"env": {
90+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}",
91+
"GITHUB_SERVER_URL": "${GITHUB_SERVER_URL}"
92+
}
93+
}
94+
}
95+
}
96+
```
97+
98+
Then run with both environment variables:
99+
100+
```bash
101+
export GITHUB_SERVER_URL="https://acme.ghe.com"
102+
export GITHUB_TOKEN="<your-copilot-cli-token>"
103+
export GITHUB_PERSONAL_ACCESS_TOKEN="<your-github-pat>"
104+
105+
sudo -E awf \
106+
--allow-domains acme.ghe.com,api.acme.ghe.com,raw.githubusercontent.com,registry.npmjs.org \
107+
--enable-api-proxy \
108+
"npx @github/copilot@latest \
109+
--disable-builtin-mcps \
110+
--allow-tool github \
111+
--prompt 'create an issue'"
112+
```
113+
114+
## GitHub Enterprise Server (GHES)
115+
116+
GitHub Enterprise Server customers host their own GitHub instance on a custom domain (e.g., `github.company.com`). AWF automatically routes Copilot API traffic to the enterprise endpoint.
117+
118+
### Automatic Configuration
119+
120+
When `GITHUB_SERVER_URL` is set to a non-github.com, non-ghe.com domain, AWF automatically routes to the GHES Copilot endpoint:
121+
122+
```bash
123+
# Example: GITHUB_SERVER_URL=https://github.company.com
124+
# AWF automatically uses: api.enterprise.githubcopilot.com
125+
```
126+
127+
### Required Domains for GHES
128+
129+
```bash
130+
export GITHUB_SERVER_URL="https://github.company.com"
131+
export GITHUB_TOKEN="<your-copilot-cli-token>"
132+
133+
sudo -E awf \
134+
--allow-domains github.company.com,api.enterprise.githubcopilot.com \
135+
--enable-api-proxy \
136+
-- npx @github/copilot@latest --prompt "your prompt here"
137+
```
138+
139+
**Domain breakdown:**
140+
- `github.company.com` - Your GHES instance (git operations, web UI)
141+
- `api.enterprise.githubcopilot.com` - Enterprise Copilot API endpoint (used for all GHES instances)
142+
143+
### GitHub Actions (GHES)
144+
145+
```yaml
146+
jobs:
147+
test:
148+
runs-on: self-hosted # GHES typically uses self-hosted runners
149+
steps:
150+
- name: Setup awf
151+
uses: github/gh-aw-firewall@main
152+
153+
- name: Run Copilot with GHES
154+
env:
155+
GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
156+
run: |
157+
sudo -E awf \
158+
--allow-domains ${{ github.server_url_hostname }},api.enterprise.githubcopilot.com \
159+
--enable-api-proxy \
160+
-- npx @github/copilot@latest --prompt "generate tests"
161+
```
162+
163+
## Manual Override
164+
165+
If automatic detection doesn't work for your setup, you can manually specify the Copilot API endpoint using the `--copilot-api-target` flag:
166+
167+
```bash
168+
# For GHEC with custom configuration
169+
sudo awf \
170+
--allow-domains acme.ghe.com,api.acme.ghe.com \
171+
--copilot-api-target api.acme.ghe.com \
172+
--enable-api-proxy \
173+
-- your-command
174+
175+
# For GHES with custom configuration
176+
sudo awf \
177+
--allow-domains github.company.com,api.enterprise.githubcopilot.com \
178+
--copilot-api-target api.enterprise.githubcopilot.com \
179+
--enable-api-proxy \
180+
-- your-command
181+
```
182+
183+
The `--copilot-api-target` flag takes precedence over automatic detection.
184+
185+
## Priority Order
186+
187+
AWF determines the Copilot API endpoint in this order:
188+
189+
1. **`--copilot-api-target` flag** (highest priority) - Manual override
190+
2. **`GITHUB_SERVER_URL` with `*.ghe.com`** - Automatic GHEC detection → `api.<subdomain>.ghe.com`
191+
3. **`GITHUB_SERVER_URL` non-github.com** - Automatic GHES detection → `api.enterprise.githubcopilot.com`
192+
4. **Default** - Public GitHub → `api.githubcopilot.com`
193+
194+
## Verification
195+
196+
To verify your configuration is working correctly:
197+
198+
### 1. Check Environment Variables
199+
200+
```bash
201+
echo "GITHUB_SERVER_URL: $GITHUB_SERVER_URL"
202+
echo "GITHUB_TOKEN: ${GITHUB_TOKEN:+[set]}"
203+
```
204+
205+
### 2. Run with Debug Logging
206+
207+
Add `--keep-containers` to inspect the configuration:
208+
209+
```bash
210+
sudo -E awf \
211+
--allow-domains acme.ghe.com,api.acme.ghe.com \
212+
--enable-api-proxy \
213+
--keep-containers \
214+
-- npx @github/copilot@latest --prompt "test"
215+
```
216+
217+
### 3. Check API Proxy Logs
218+
219+
```bash
220+
# View the derived endpoint in startup logs
221+
docker logs awf-api-proxy | grep "Copilot proxy"
222+
223+
# Expected for GHEC:
224+
# Copilot proxy listening on port 10002 (target: api.acme.ghe.com)
225+
226+
# Expected for GHES:
227+
# Copilot proxy listening on port 10002 (target: api.enterprise.githubcopilot.com)
228+
```
229+
230+
### 4. Check Squid Logs
231+
232+
```bash
233+
# View allowed/denied requests
234+
sudo cat /tmp/squid-logs-*/access.log | grep copilot
235+
236+
# Verify traffic is going to the correct endpoint
237+
```
238+
239+
## Troubleshooting
240+
241+
### Wrong API Endpoint
242+
243+
**Problem:** Traffic is going to the wrong Copilot API endpoint
244+
245+
**Solutions:**
246+
1. Check that `GITHUB_SERVER_URL` is set correctly and exported
247+
2. Use `sudo -E` to preserve environment variables when running awf
248+
3. Use `--copilot-api-target` to manually override if needed
249+
4. Verify the domain is in your `--allow-domains` list
250+
251+
### Domain Not Whitelisted
252+
253+
**Problem:** Requests are blocked with "TCP_DENIED"
254+
255+
**Solution:** Add the missing domain to `--allow-domains`:
256+
257+
```bash
258+
# Check Squid logs for blocked domains
259+
sudo cat /tmp/squid-logs-*/access.log | grep TCP_DENIED
260+
261+
# Add the blocked domain to your allowlist
262+
sudo -E awf \
263+
--allow-domains acme.ghe.com,api.acme.ghe.com,<blocked-domain> \
264+
--enable-api-proxy \
265+
-- your-command
266+
```
267+
268+
### MCP Server Not Connecting to GHEC
269+
270+
**Problem:** GitHub MCP server fails to connect to your GHEC instance
271+
272+
**Solutions:**
273+
1. Ensure `GITHUB_SERVER_URL` is in the MCP server environment variables
274+
2. Add your GHEC domain to `--allow-domains`
275+
3. Verify `GITHUB_PERSONAL_ACCESS_TOKEN` has the correct scopes for your GHEC tenant
276+
277+
### Invalid GITHUB_SERVER_URL
278+
279+
**Problem:** AWF falls back to default (public GitHub) even though you set GITHUB_SERVER_URL
280+
281+
**Solutions:**
282+
1. Verify the URL format is correct: `https://hostname` (with protocol)
283+
2. Check that the variable is exported before running awf
284+
3. Use `sudo -E` to preserve environment variables
285+
286+
## Examples
287+
288+
### Complete GHEC Setup
289+
290+
```bash
291+
# 1. Set environment variables
292+
export GITHUB_SERVER_URL="https://acme.ghe.com"
293+
export GITHUB_TOKEN="ghp_..."
294+
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_..."
295+
296+
# 2. Create MCP config (if using GitHub MCP server)
297+
mkdir -p ~/.copilot
298+
cat > ~/.copilot/mcp-config.json << 'EOF'
299+
{
300+
"mcpServers": {
301+
"github": {
302+
"type": "local",
303+
"command": "docker",
304+
"args": [
305+
"run", "-i", "--rm",
306+
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
307+
"-e", "GITHUB_SERVER_URL",
308+
"ghcr.io/github/github-mcp-server:latest"
309+
],
310+
"tools": ["*"],
311+
"env": {
312+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}",
313+
"GITHUB_SERVER_URL": "${GITHUB_SERVER_URL}"
314+
}
315+
}
316+
}
317+
}
318+
EOF
319+
320+
# 3. Pull MCP server image
321+
docker pull ghcr.io/github/github-mcp-server:latest
322+
323+
# 4. Run Copilot with AWF
324+
sudo -E awf \
325+
--allow-domains acme.ghe.com,api.acme.ghe.com,raw.githubusercontent.com,registry.npmjs.org \
326+
--enable-api-proxy \
327+
"npx @github/copilot@latest \
328+
--disable-builtin-mcps \
329+
--allow-tool github \
330+
--prompt 'create an issue in repo/name'"
331+
```
332+
333+
### Complete GHES Setup
334+
335+
```bash
336+
# 1. Set environment variables
337+
export GITHUB_SERVER_URL="https://github.company.com"
338+
export GITHUB_TOKEN="ghp_..."
339+
340+
# 2. Run Copilot with AWF
341+
sudo -E awf \
342+
--allow-domains github.company.com,api.enterprise.githubcopilot.com \
343+
--enable-api-proxy \
344+
-- npx @github/copilot@latest --prompt "your prompt here"
345+
```
346+
347+
## See Also
348+
349+
- [API Proxy Sidecar](api-proxy-sidecar.md) - Secure credential management architecture
350+
- [GitHub Actions Integration](github_actions.md) - CI/CD setup with AWF
351+
- [Environment Variables](environment.md) - Environment variable configuration
352+
- [Usage Guide](usage.md) - General CLI usage and examples
353+
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

0 commit comments

Comments
 (0)