# Copilot Cloud Agent — Firewall Configuration

This document explains the sandbox firewall behaviour for GitHub Copilot cloud
(coding) agents, lists the external hosts agents need to reach at task time,
and gives the exact steps to unblock them.

## Background

When a Copilot coding agent runs, it goes through two phases:

1. **Setup phase** — the `copilot-setup-steps` job in
   `.github/workflows/copilot-setup-steps.yml` runs.  The network is **open**
   during this phase, so all `pip install`, `npm install`, and similar commands
   complete successfully.

2. **Task phase** — the agent executes the actual task.  After setup, the
   sandbox firewall **denies all egress by default**.  Only hosts explicitly
   listed in the repo/org allowlist may be reached.

### Root cause of blocked sessions

A prior agent session (`179e2637-a27d-40e7-8d02-2a2b3694ddc1`) stalled because
`api.github.com` and `github.com` were not in the allowlist.  The agent could
not read a PR review comment body via `gh api`, `curl`, or `web_fetch`.  The
sandbox logs confirmed the default allowlist included package-registry and
raw-content hosts but **not** the GitHub REST/GraphQL API.

## Required hosts

The table below lists every external host agents need, with the reason each is
required.

| Host | Reason |
|------|--------|
| `api.github.com` | GitHub REST/GraphQL API — reading PR review comments, resolving threads, writing comments |
| `github.com` | GitHub web — cloning, pushing, `gh` CLI operations |
| `uploads.github.com` | GitHub upload endpoint used by `gh` workflows |
| `pypi.org` | Python package index — `pip`/`uv` installs at task time |
| `files.pythonhosted.org` | PyPI package file downloads |
| `upload.pypi.org` | `twine` publishing (release workflows) |
| `registry.npmjs.org` | npm packages — `markdownlint-cli2` and other Node tooling |
| `dev.azure.com` | Azure DevOps REST API used by `agentic_devtools/cli/azure_devops/` |
| `*.visualstudio.com` | Legacy Azure DevOps endpoints |
| `vssps.dev.azure.com` | Azure DevOps identity/profile service |
| `ssh.dev.azure.com` | Azure DevOps SSH git access |
| `login.microsoftonline.com` | Azure identity token acquisition (`azure-identity`) |
| `login.microsoft.com` | Alternate Azure login endpoint |
| `management.azure.com` | Azure Resource Manager API |
| `*.monitor.azure.com` | Azure Monitor ingestion endpoints |
| `api.loganalytics.io` | Log Analytics / Application Insights queries (`azure-monitor-query`) |
| `*.atlassian.net` | Jira REST API (`atlassian-python-api` — issues, comments, epics) |
| `api.atlassian.com` | Atlassian platform API |
| `api.openai.com` | OpenAI API (`openai` Python package) |

## How to add hosts to the allowlist

### Step 1 — Settings UI (enforced by the platform)

1. Navigate to **Settings → Copilot → Coding agent**.
2. Under **Custom allowlist**, add each host from the table above.
3. Save changes.

The committed file `.github/copilot/firewall-allowlist.yml` documents the same
list in version control; the Settings allowlist is what the platform actually
enforces.

### Step 2 — Minimum set to unblock the common case

If you only need to unblock GitHub API calls (the most common blocker):

```text
api.github.com
github.com
uploads.github.com
```

For full agent functionality (Jira, Azure DevOps, OpenAI, publishing):

```text
api.github.com
github.com
uploads.github.com
pypi.org
files.pythonhosted.org
upload.pypi.org
registry.npmjs.org
dev.azure.com
*.visualstudio.com
vssps.dev.azure.com
ssh.dev.azure.com
login.microsoftonline.com
login.microsoft.com
management.azure.com
*.monitor.azure.com
api.loganalytics.io
*.atlassian.net
api.atlassian.com
api.openai.com
```

## Best practice: install at setup time

The sandbox network is **open during setup**.  Move any network-dependent
installs into `.github/workflows/copilot-setup-steps.yml` so they complete
before the firewall closes.  Only add a host to the allowlist if the agent
genuinely needs to reach it *during* a task (not just at install time).

## See also

- `.github/copilot/firewall-allowlist.yml` — version-controlled host list
- `.github/workflows/copilot-setup-steps.yml` — agent setup workflow
