Enterprise Configuration

Enterprise Configuration

This page covers configuration options specific to GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC) deployments.

GitHub Enterprise Server (GHES) Compatibility

GHES Compatibility Mode

GHES instances running versions that predate @actions/artifact v2.0.0 support cannot use actions/upload-artifact@v4+ or actions/download-artifact@v4+. Attempting to run compiled workflows on these instances produces a GHESNotSupportedError.

gh-aw includes a GHES compatibility mode toggle (aw.json ghes or gh aw compile --ghes) for GHES releases that require the v3 artifact backend. Compatibility mode emits upload-artifact@v3.2.2 and download-artifact@v3.1.0; default GitHub.com compilation continues to use the latest artifact actions.

This compatibility path supports GHES 3.21.x and earlier when the workflow runs on Actions Runner 2.327.1 or later, which is required by the Node.js 24 runtime used by these pinned artifact actions. For later GHES releases, keep compatibility mode enabled until your instance supports the v4 artifact backend.

Enable via aw.json (recommended)

Set ghes: true in .github/workflows/aw.json to apply GHES compatibility to every workflow compiled in the repository:

{
  "ghes": true
}

Auto-detection with gh aw init

Running gh aw init inside a GHES repository automatically detects the deployment and writes ghes: true to .github/workflows/aw.json. No manual configuration is required.

Enable via CLI flag

Pass --ghes to gh aw compile for a one-off compilation without modifying aw.json:

gh aw compile --ghes my-workflow.md

Note

The --ghes flag only affects the current compilation. Use aw.json to apply GHES compatibility permanently across all workflows in the repository.

GitHub Enterprise Server CLI Setup

For gh CLI configuration, host authentication, and GH_HOST setup on GHES, see GitHub Enterprise Server Support in the CLI reference.

Copilot Engine on GHES

For Copilot-specific prerequisites, licensing requirements, and firewall configuration on GHES, see Copilot Engine Prerequisites on GHES.