Actions Native Egress Firewall: Early Access

Welcome to the early access program for the GitHub Actions native egress firewall. This program gives design partners hands on access to log and file-based enforcement for GitHub-hosted runners.

Getting started in early access

The native egress firewall builds on GitHub Actions' existing runner image architecture, but operates within the context of a nested-VM. Separating the runner from the firewall. We provide both a standard firewall enabled runner image and a larger firewall enabled runner image, giving customers the same image options they use today with native egress controls included. For now, logs are available as an artifact at the conclusion of a workflow run.

Runner access in early access:

• Standard GitHub-hosted runners are available by default. Set runs-on: ubuntu-24.04-firewall in your workflow file.
• Larger runners are available by request during technical preview. Open a larger runner access request and include:
  • whether access is for an enterprise or organization
  • the exact enterprise or organization name
  • a point of contact

After approval, ask your administrator to create a Linux larger runner using the GitHub-maintained Ubuntu 24.04 with Firewall image.

What is the native egress firewall?

GitHub hosted runners today allow unrestricted outbound network access. Any workflow can reach any host on the internet, regardless of GITHUB_TOKEN permissions, secret scoping, OIDC, or SHA pinning. Those controls govern identity, code, and what the workflow can do inside GitHub, but nothing today governs where the workflow can talk on the network.

The native egress firewall closes that gap. It runs outside the runner VM, inspects DNS and HTTP/HTTPS traffic, and remains immutable even if a workflow gains root access inside the runner. It complements OIDC, SHA pinning, and GITHUB_TOKEN permissions but does not replace them; together they produce a workflow that is identified, deterministic, least-privileged, and network-bounded.

The capability ships in two modes:

• Log mode records every outbound DNS lookup and HTTP request without blocking anything. This is the safe entry point.
• enforce mode applies an allow list. Traffic outside the list is blocked by default, recorded, and surfaced in the workflow summary with the offending command and the rule that denied it.

How HTTPS inspection works

To support URL-level allow rules, the firewall terminates TLS at the egress boundary and re-establishes TLS to the destination. Each workflow run gets a unique, ephemeral certificate that is destroyed when the run ends, so traffic remains private to that run.

• If your workflow trusts the operating system certificate store (the default for curl, git, npm, pip, docker, etc.), you will see a normal HTTPS connection. No changes are required.
• If your workflow does certificate pinning or mTLS, you will need to update it to trust the per-run ephemeral certificate.

File-based enforcement

File-based enforcement defines egress policy in a configuration file committed to your repository. The firewall evaluates that policy at the egress boundary. The file declares a mode and an allow list; in enforce mode, traffic to hosts outside the allow list is denied by default, recorded, and surfaced back to you.

Keeping policy alongside a workflow makes it reviewable in pull requests, version controlled, diffable, and portable with the repository. Use file-based rules when those policy-as-code properties fit your workflow. They can be used instead of, or alongside, other available rule formats.

Where the policy file goes

Follow these steps to add the policy file:

1. Create (or open) the .github directory at the root of the repository that contains your workflow.
2. Add a file named egress-firewall.yaml in that directory — the full path must be .github/egress-firewall.yaml.
3. Define your policy in that file (see the configuration example below).
4. Commit the file to the branch the workflow will run from.

your-repo/
├── .github/
│   ├── egress-firewall.yaml   # ✅ policy file goes here
│   └── workflows/
│       └── ci.yml             # ❌ do NOT put egress-firewall.yaml here

Configuration example

The policy file is committed to the repository with the workflow it protects. For this technical preview, use the path and filename documented above. The path, filename, and discovery mechanism may change; follow updated onboarding guidance supplied to preview participants.

By default, policies allow egress to:

• github.com
• *blob.core.windows.net (*)
• codeload.github.com
• *actions.githubusercontent.com (*)

The (*) entries are GitHub-managed defaults, not user-configurable wildcard patterns. The firewall expands them to matching URLs returned by the GitHub /meta endpoint, so the allowed set cannot escape GitHub-controlled endpoints.

The following example adds api.github.com and release-assets.githubusercontent.com; the other GitHub endpoints shown above are already covered by the default allow list.

mode: enforce
allow:
  - api.github.com
  - release-assets.githubusercontent.com

• mode selects behavior: enforce denies hosts not matched by allow; log records traffic without intentionally denying it.
• allow adds hosts to the default allow list.

Building your allow list

For the initial run, set mode: log. Use the resulting list of outbound URLs and hosts that were requested to construct your allow list before switching to mode: enforce. Customers using GitHub Enterprise Cloud with data residency may have additional steps when constructing their allow list because their endpoints and hostnames differ from the standard github.com endpoints. Consult the meta endpoint for your own tenant and region.

The GitHub Enterprise Cloud meta endpoint can help you understand which groups of domains a particular request belongs to. For example, if a run reaches out to pipelinesghubeus47.actions.githubusercontent.com, you may also want to add pipelinesghubeus48.actions.githubusercontent.com, since they are members of the same domain group returned by /meta.

Set no-default-urls: true to disable the default allow list. You must then explicitly list every endpoint your workflow needs, including GitHub endpoints such as github.com and codeload.github.com.

mode: enforce
no-default-urls: true
allow:
  - github.com
  - api.github.com
  - codeload.github.com

The following workflow uses the firewall runner with the additive policy example. The first request is allowed; the PyPI request is a representative CI dependency lookup to a host not in the allow list, so it fails in enforce mode.

name: Test firewall policy

on:
  workflow_dispatch:

jobs:
  egress:
    runs-on: ubuntu-24.04-firewall
    steps:
      - name: Allowed GitHub API request
        run: curl --fail --silent --show-error https://api.github.com
      - name: Blocked PyPI dependency lookup
        run: curl --fail --silent --show-error https://pypi.org/simple/requests/

Enforcement results and reporting

In enforce mode, a request to a denied host fails from inside the workflow as a failed connection or request error in the affected step. The workflow run summary identifies the denied traffic, including the offending command or binary and the rule that denied it.

Preview firewall events are surfaced in the workflow run summary and as a workflow run artifact. Events include the binary name, without command-line flags or environment variables, and the URL without query arguments or URL fragments. Avoid placing secrets in command names or URL paths.

Two delivery paths

Adoption path	Runner type	How it is enabled	Best for
Firewall enabled label	Standard GitHub hosted runners	Set runs-on: ubuntu-24.04-firewall in the workflow	Individual repositories, open source projects, fast adoption with no admin setup
Firewall enabled image	Larger runners	Select the GitHub maintained Ubuntu 24.04 with Firewall image when creating the larger runner	Enterprises that already use larger runners, custom tooling, private networking, or runner groups

Both paths produce identical Layer 7 enforcement, identical telemetry, and identical rule semantics. Custom larger runner images built on the firewall base image cannot disable or bypass the firewall, because enforcement lives outside the VM.

Phased rollout

Phase	Capability	Scope
Technical preview	Log mode and file-based enforcement with allow list rules. Deny all by default in enforce mode	Linux, opt in via runner label or larger runner image
Public preview	Expanded policy and administration experiences, informed by preview feedback	Scope to be determined
GA	Further capability expansion, informed by customer feedback	Scope to be determined

Where logs go

• Preview: firewall events are surfaced in the workflow run summary and as a workflow run artifact. We will log the binary name (without command line flags or environment variables) as well as the URL (without query arguments or URL fragment). Be careful that you don't accidentally log secrets in your command name or URL path!
• GA: events stream to the Actions data stream with workflow, job, step, and command attribution, ready for ingestion into existing SIEM and detection pipelines.

Feedback Requested

Technical preview participants: please tell us about your experience with:

• File-based rule authoring, including how policy changes fit into pull request review.

• The rule format and schema.

• The shape and usefulness of returned enforcement data.

• Logging, observability, and troubleshooting.

• Missing capabilities, edge cases, and scale requirements.

• Issue report: report a bug, blocked request, false positive, or unexpected behavior.

• Feature request: request a new rule kind, a managed rule, or a platform expansion.

• Larger runner access request: request early access to larger runners using the Ubuntu 24.04 with Firewall image.

Future Direction and Scale Considerations

We recognize that many customers need to manage and enforce egress policies consistently across large organizations and enterprises. Managing policy across hundreds or thousands of repositories remains an important requirement for many customers.

Organization-level and enterprise-level management, governance, and policy distribution are not the focus of this technical preview. The immediate goal is to provide meaningful enforcement and validation so customers can begin protecting workflows and provide feedback on the policy model. Feedback gathered during preview will inform future investments in large-scale policy management and administration experiences.