Skip to content

Commit 0c5eca0

Browse files
CopilotlpcoxCopilot
authored
fix: always route Gemini through api-proxy sidecar when --enable-api-proxy is active (#1946)
* Initial plan * fix: always set GEMINI_API_BASE_URL when api-proxy enabled When --enable-api-proxy is active, set GEMINI_API_BASE_URL and the GEMINI_API_KEY placeholder unconditionally in the agent environment, regardless of whether config.geminiApiKey is present in the AWF runner environment. Previously, both were only set when config.geminiApiKey was truthy, causing the Gemini CLI to fail with exit code 41 ("no auth method") whenever the key was available only as a GitHub Actions secret and not as a runner-level env var. The api-proxy sidecar returns 503 when the real key is absent — a clear, actionable failure vs a confusing missing-auth error. Also update docs/api-proxy-sidecar.md to: - Add GEMINI_API_KEY to the api-proxy env table - Add GEMINI_API_BASE_URL / GEMINI_API_KEY placeholder rows to the agent env table with a :::note explaining the always-set behaviour - Add GitHub Actions caution note in the required env vars section - Add a Gemini CLI exit-code-41 troubleshooting entry - Fix the Limitations section (was incorrectly "only OpenAI/Anthropic") - Fix the container ports list to include port 10003 (Gemini) Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/d29ba1a1-4886-4755-ab93-12a3eb6fa4a3 * fix: address review feedback on Gemini docs - Add COPILOT_GITHUB_TOKEN/COPILOT_API_KEY to required env vars list - Add sudo --preserve-env note for GitHub Actions usage - Update troubleshooting: exit 41 replaced by 503 (placeholder key now satisfies CLI pre-flight) - Update 'API keys not detected' message to list all providers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Landon Cox <landon.cox@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 3185587 commit 0c5eca0

3 files changed

Lines changed: 85 additions & 21 deletions

File tree

‎docs/api-proxy-sidecar.md‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ The API proxy sidecar receives **real credentials** and routing configuration:
124124
| `ANTHROPIC_API_KEY` | Real API key | `--enable-api-proxy` and env set | Anthropic API key (injected into requests) |
125125
| `COPILOT_GITHUB_TOKEN` | Real token | `--enable-api-proxy` and env set | GitHub Copilot token (injected into requests) |
126126
| `COPILOT_API_KEY` | Real API key | `--enable-api-proxy` and env set | GitHub Copilot BYOK key (injected into requests) |
127+
| `GEMINI_API_KEY` | Real API key | `--enable-api-proxy` and env set | Google Gemini API key (injected into requests) |
127128
| `HTTP_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid for domain filtering |
128129
| `HTTPS_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid for domain filtering |
129130

@@ -148,6 +149,8 @@ The agent container receives **redacted placeholders** and proxy URLs:
148149
| `COPILOT_OFFLINE` | `true` | `COPILOT_API_KEY` provided to host | Enables offline+BYOK mode (skips GitHub OAuth handshake) |
149150
| `COPILOT_PROVIDER_BASE_URL` | `http://172.30.0.30:10002` | `COPILOT_API_KEY` provided to host | Points Copilot CLI BYOK provider at sidecar |
150151
| `COPILOT_PROVIDER_API_KEY` | `placeholder-token-for-credential-isolation` | `COPILOT_API_KEY` provided to host | BYOK provider API key placeholder (real key in sidecar) |
152+
| `GEMINI_API_BASE_URL` | `http://172.30.0.30:10003` | `--enable-api-proxy` always | Redirects Gemini CLI to proxy (set unconditionally — see note below) |
153+
| `GEMINI_API_KEY` | `gemini-api-key-placeholder-for-credential-isolation` | `--enable-api-proxy` always | Placeholder so Gemini CLI auth check passes (real key in sidecar) |
151154
| `OPENAI_API_KEY` | Not set | `--enable-api-proxy` | Excluded from agent (held in api-proxy) |
152155
| `ANTHROPIC_API_KEY` | Not set | `--enable-api-proxy` | Excluded from agent (held in api-proxy) |
153156
| `HTTP_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid proxy |
@@ -156,6 +159,14 @@ The agent container receives **redacted placeholders** and proxy URLs:
156159
| `AWF_API_PROXY_IP` | `172.30.0.30` | `--enable-api-proxy` | Used by iptables setup script |
157160
| `AWF_ONE_SHOT_TOKENS` | `COPILOT_GITHUB_TOKEN,GITHUB_TOKEN,...` | Always | Tokens protected by one-shot-token library |
158161

162+
:::note[Gemini always redirected to proxy]
163+
Unlike OpenAI, Anthropic, and Copilot, `GEMINI_API_BASE_URL` and the `GEMINI_API_KEY` placeholder are **always** set in the agent when `--enable-api-proxy` is active, regardless of whether `GEMINI_API_KEY` is present in the runner environment.
164+
165+
This prevents the Gemini CLI from failing with exit code 41 ("no auth method") when the real API key is only available as a GitHub Actions secret (not as a runner-level environment variable). In that case the api-proxy sidecar will return `503` for Gemini requests — a clear, actionable failure rather than a confusing missing-auth error.
166+
167+
**Important**: `GEMINI_API_KEY` must be set as a **runner-level environment variable** (e.g. `env: GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}` in the workflow step), not only as a GitHub Actions secret. The AWF process running on the runner must be able to read it so it can pass the key to the api-proxy sidecar container.
168+
:::
169+
159170
:::tip[Placeholder tokens]
160171
Token variables in the agent are set to `placeholder-token-for-credential-isolation` instead of real values. This ensures:
161172
- Agent code cannot exfiltrate credentials
@@ -262,6 +273,24 @@ sudo awf --enable-api-proxy [OPTIONS] -- COMMAND
262273
**Required environment variables** (at least one):
263274
- `OPENAI_API_KEY` — OpenAI API key
264275
- `ANTHROPIC_API_KEY` — Anthropic API key
276+
- `GEMINI_API_KEY` — Google Gemini API key
277+
- `COPILOT_GITHUB_TOKEN` — GitHub Copilot access token
278+
- `COPILOT_API_KEY` — GitHub Copilot API key (BYOK)
279+
280+
:::caution[GitHub Actions: expose keys as runner env vars]
281+
When running AWF in a GitHub Actions workflow, API keys must be available as **runner-level environment variables** — not just as GitHub Actions secrets. AWF reads the key from the environment at startup to pass it to the api-proxy sidecar container. Use `env:` in the workflow step and `sudo --preserve-env` to ensure keys pass through:
282+
283+
```yaml
284+
- name: Run agent
285+
env:
286+
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
287+
run: sudo --preserve-env=GEMINI_API_KEY awf --enable-api-proxy ...
288+
```
289+
290+
> **Note:** `sudo` strips most environment variables by default. Use `--preserve-env=VAR` (or `sudo -E` to preserve all) to ensure API keys are visible to the AWF process.
291+
292+
If the key is present only in `secrets.*` but not exported into the step's `env:`, AWF will warn that no Gemini key was found and the api-proxy Gemini listener will return `503`.
293+
:::
265294

266295
**Recommended domain whitelist**:
267296
- `api.openai.com` — for OpenAI/Codex
@@ -283,7 +312,7 @@ The sidecar container:
283312
- **Image**: `ghcr.io/github/gh-aw-firewall/api-proxy:latest`
284313
- **Base**: `node:22-alpine`
285314
- **Network**: `awf-net` at `172.30.0.30`
286-
- **Ports**: 10000 (OpenAI), 10001 (Anthropic), 10002 (GitHub Copilot)
315+
- **Ports**: 10000 (OpenAI), 10001 (Anthropic), 10002 (GitHub Copilot), 10003 (Google Gemini)
287316
- **Proxy**: Routes via Squid at `http://172.30.0.10:3128`
288317

289318
### Health check
@@ -296,14 +325,33 @@ Docker healthcheck on the `/health` endpoint (port 10000):
296325

297326
## Troubleshooting
298327

328+
### Gemini proxy returns 503
329+
330+
When `--enable-api-proxy` is active, `GEMINI_API_BASE_URL` and a placeholder `GEMINI_API_KEY` are always injected into the agent container. If the real `GEMINI_API_KEY` was not set in the AWF runner environment, the api-proxy Gemini listener (port 10003) responds with **503** to all requests.
331+
332+
**Solution**: Export `GEMINI_API_KEY` in the runner environment before invoking AWF. In GitHub Actions, add it to the step's `env:` block and use `sudo --preserve-env`:
333+
334+
```yaml
335+
- name: Run Gemini agent
336+
env:
337+
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
338+
run: |
339+
sudo --preserve-env=GEMINI_API_KEY \
340+
awf --enable-api-proxy \
341+
--allow-domains generativelanguage.googleapis.com \
342+
-- gemini ...
343+
```
344+
345+
> **Note:** Exit code 41 ("no auth method") should no longer occur with `--enable-api-proxy` since the placeholder key satisfies the CLI's pre-flight check. If you see exit 41, ensure `--enable-api-proxy` is active.
346+
299347
### API keys not detected
300348

301349
```
302350
⚠️ API proxy enabled but no API keys found in environment
303-
Set OPENAI_API_KEY or ANTHROPIC_API_KEY to use the proxy
351+
Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, COPILOT_GITHUB_TOKEN, or COPILOT_API_KEY to use the proxy
304352
```
305353
306-
**Solution**: Export API keys before running awf:
354+
**Solution**: Export API keys before running awf (use `sudo --preserve-env` in CI):
307355
308356
```bash
309357
export OPENAI_API_KEY="sk-..."
@@ -343,9 +391,8 @@ docker exec awf-squid cat /var/log/squid/access.log | grep DENIED
343391

344392
## Limitations
345393

346-
- Only supports OpenAI and Anthropic APIs
347394
- Keys must be set as environment variables (not file-based)
348-
- No support for Azure OpenAI endpoints
395+
- No support for Azure OpenAI endpoints (use `--openai-api-target` for custom endpoints)
349396
- No request/response logging (by design, for security)
350397

351398
## Related documentation

‎src/docker-manager.test.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2713,12 +2713,24 @@ describe('docker-manager', () => {
27132713
expect(env.GEMINI_API_KEY).toBe('gemini-api-key-placeholder-for-credential-isolation');
27142714
});
27152715

2716-
it('should not set GEMINI_API_BASE_URL in agent when geminiApiKey is not provided', () => {
2716+
it('should always set GEMINI_API_BASE_URL in agent when api-proxy is enabled (regardless of geminiApiKey)', () => {
27172717
const configWithProxy = { ...mockConfig, enableApiProxy: true, openaiApiKey: 'sk-test-key' };
27182718
const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
27192719
const agent = result.services.agent;
27202720
const env = agent.environment as Record<string, string>;
2721-
expect(env.GEMINI_API_BASE_URL).toBeUndefined();
2721+
// GEMINI_API_BASE_URL must be set even without a geminiApiKey so that the
2722+
// Gemini CLI does not fail with exit code 41 ("no auth method") when the
2723+
// GEMINI_API_KEY is only available as a GitHub Actions secret.
2724+
expect(env.GEMINI_API_BASE_URL).toBe('http://172.30.0.30:10003');
2725+
});
2726+
2727+
it('should set GEMINI_API_KEY placeholder in agent when api-proxy is enabled without geminiApiKey', () => {
2728+
const configWithProxy = { ...mockConfig, enableApiProxy: true, openaiApiKey: 'sk-test-key' };
2729+
const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
2730+
const agent = result.services.agent;
2731+
const env = agent.environment as Record<string, string>;
2732+
// Placeholder is required so Gemini CLI's startup auth check passes (exit code 41).
2733+
expect(env.GEMINI_API_KEY).toBe('gemini-api-key-placeholder-for-credential-isolation');
27222734
});
27232735

27242736
it('should not leak GEMINI_API_KEY to agent when api-proxy is enabled', () => {

‎src/docker-manager.ts‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1654,21 +1654,26 @@ export function generateDockerCompose(
16541654
// Set early placeholder (before this block) already handled above.
16551655
logger.debug('COPILOT_PROVIDER_API_KEY placeholder set for credential isolation');
16561656
}
1657-
if (config.geminiApiKey) {
1658-
environment.GEMINI_API_BASE_URL = `http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`;
1659-
logger.debug(`Google Gemini API will be proxied through sidecar at http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`);
1660-
if (config.geminiApiTarget) {
1661-
logger.debug(`Gemini API target overridden to: ${config.geminiApiTarget}`);
1662-
}
1663-
if (config.geminiApiBasePath) {
1664-
logger.debug(`Gemini API base path set to: ${config.geminiApiBasePath}`);
1665-
}
1657+
// Always point the agent at the Gemini sidecar whenever --enable-api-proxy is active,
1658+
// regardless of whether GEMINI_API_KEY is present in the AWF runner environment.
1659+
// This prevents the Gemini CLI from failing with "no auth method" (exit code 41)
1660+
// when the key is only available as a GitHub Actions secret (not an env var visible
1661+
// to the AWF process itself). The sidecar returns 503 when the key is absent —
1662+
// a clear, actionable failure rather than a confusing missing-auth error.
1663+
environment.GEMINI_API_BASE_URL = `http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`;
1664+
logger.debug(`Google Gemini API will be proxied through sidecar at http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`);
1665+
if (config.geminiApiTarget) {
1666+
logger.debug(`Gemini API target overridden to: ${config.geminiApiTarget}`);
1667+
}
1668+
if (config.geminiApiBasePath) {
1669+
logger.debug(`Gemini API base path set to: ${config.geminiApiBasePath}`);
1670+
}
16661671

1667-
// Set placeholder key so Gemini CLI's startup auth check passes (exit code 41).
1668-
// Real authentication happens via GEMINI_API_BASE_URL pointing to api-proxy.
1669-
environment.GEMINI_API_KEY = 'gemini-api-key-placeholder-for-credential-isolation';
1670-
logger.debug('GEMINI_API_KEY set to placeholder value for credential isolation');
1671-
} else {
1672+
// Set placeholder key so Gemini CLI's startup auth check passes (exit code 41).
1673+
// Real authentication happens via GEMINI_API_BASE_URL pointing to api-proxy.
1674+
environment.GEMINI_API_KEY = 'gemini-api-key-placeholder-for-credential-isolation';
1675+
logger.debug('GEMINI_API_KEY set to placeholder value for credential isolation');
1676+
if (!config.geminiApiKey) {
16721677
logger.warn('--enable-api-proxy is active but GEMINI_API_KEY is not set.');
16731678
logger.warn(` The api-proxy Gemini listener (port ${API_PROXY_PORTS.GEMINI}) will start in fallback mode and return 503 responses until GEMINI_API_KEY is set.`);
16741679
logger.warn(' Set GEMINI_API_KEY in the AWF runner environment to enable Gemini credential isolation.');

0 commit comments

Comments
 (0)