Policy File Reference

Policy files in IronCD define how runners are allowed to communicate with external systems. They are used to control network egress and protocol access from within each job’s isolated VM.

IronCD enforces these policies using a proprietary network proxy layer on the host system.

Overview

Each repository in IronCD must define an egress policy file at .ironcd/policy.yml. The policy tells IronCD which destinations are allowed to be reached by started by that repository. Some hosts - such as those used by GitHub Actions itself - are automatically allowed by IronCD. IronCD maintains a list of these hosts and updates it regularly.

If no policy is provided, IronCD will refuse to start any jobs for that repository. IronCD will make you aware of this issue by setting a failed commit status on the repository.

Important

All hosts are assumed to be HTTPS. HTTP (i.e., non-TLS) traffic is not allowed.

Example


# .ironcd/policy.yml
mode: enforce
allow:
  - preset: node
  - host: "*.example.com"

This configuration allows HTTPS traffic to common Node.js development hosts through the node preset, and additionally allows access to all first-level subdomains of example.com.

By setting mode to enforce, IronCD will block any traffic that does not match the allowed destinations. If you want to observe the traffic without blocking it (e.g., for debugging purposes), set mode to warn.

Fields

Field	Type	Description
`mode`	string	Either `enforce` or `warn`.
`allow`	array	List of allowed destinations.
`allow.preset`	string	A named rule bundle managed by IronCD.
`allow.host`	string	A specific hostname or wildcard domain pattern.

`mode`

Defines how IronCD enforces the policy:

Mode	Behavior
`enforce`	Blocks all outbound traffic not explicitly allowed.
`warn`	Logs denied traffic but does not block it.

`allow`

The allow section defines permitted outbound destinations. Each item can reference either a preset or a host. You cannot specify both a preset and a host in the allow rule.

Example: Presets


allow:
  - preset: node
  - preset: ruby

Presets are predefined lists of hosts maintained by IronCD. The following presets are available:

Preset	Description	Example Hosts
github-actions	Required for workflows using GitHub Actions or GitHub-hosted resources. Automatically added by IronCD for GitHub Actions workflows.	`api.github.com`
npm	Enables access to NPM and Yarn registries.	`registry.npmjs.org`
pypi	Enables access to Python package registries.	`pypi.org`
golang	Enables Go module proxy and checksum servers.	`proxy.golang.org`
rust	Enables Rust crate fetching and index access.	`crates.io`
ruby	Enables RubyGems downloads and updates.	`rubygems.org`
java	Enables Maven Central repositories.	`repo.maven.apache.org`
docker	Enables access to major container registries.	`registry-1.docker.io`
ubuntu	Enables access to Ubuntu apt mirrors and security updates.	`security.ubuntu.com`, `*.archive.ubuntu.com`
all-https	Aggregates all of the above presets into a single ruleset.	All hosts from every preset above.

Example: Custom Hosts

If a preset doesn’t cover your use case, you can also allow custom hosts.


allow:
  - host: "api.stripe.com"
  - host: "*.corp.internal"

Custom hosts support wildcards. Note that wildcards apply to only one level of the domain. For example, *.corp.com will match api.corp.com but not prod.api.corp.com.

Evaluation

IronCD evaluates the policy as follows:

The policy is loaded before the VM starts.
Each outbound connection attempt is matched against the allow list.
If a match is found, the connection is allowed.
Otherwise:
- In enforce mode, the connection is denied and logged as a policy violation.
- In warn mode, the connection is allowed but logged as a policy violation.

Validation

When a workflow starts, IronCD validates that:

The policy file is present and valid YAML.
All preset references exist.
Host patterns are syntactically valid.

If validation fails, the job will not start and IronCD will set the commit status on your build to failed.

Logs and Audit

All outbound connection attempts are logged with:

Timestamp
Runner ID and job ID
Target hostname and port
Matched rule or preset
Action taken (allow, deny, or warn)

Logs can be viewed in on the Console Dashboard

Examples

Observation Mode


mode: observe
allow:
  - preset: all-https

Permits common connections but logs policy violations instead of blocking them. Useful during onboarding or migration.

JSON Schema


{
  "title": "IronCD Policy Schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": ["warn", "enforce"]
    },
    "allow": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "preset": { "type": "string" },
          "host": { "type": "string" }
        },
        "allOf": [
          {
            "not": {
              "required": ["preset", "host"]
            }
          }
        ],
        "anyOf": [{ "required": ["preset"] }, { "required": ["host"] }]
      }
    }
  },
  "required": ["mode", "allow"]
}