GitHub Enterprise Server and GHE.com

RunsOn works with GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud with data residency (GHE.com), as well as github.com. Flex and Fleet support all three.

You install the same stack and give it the web URL of your GitHub. RunsOn derives the API, webhook and token endpoints from that URL. The rest of the Flex or Fleet install guide applies as written.

The URL to set#

Use the URL you open in a browser, over https. A *.ghe.com host is treated as GHE.com. Any other host except github.com is treated as GitHub Enterprise Server.

For GHE.com, install RunsOn in an AWS region in the same geography as your tenant. The runners, their cache bucket and the control plane all live in that region, in your account.

Flex#

CloudFormation#

Set GithubEnterpriseUrl when you create the stack, before you register the GitHub App. The parameter is available from v3.5.0. Keep EnableWAF=false (see Networking).

Then follow the Flex install guide. The setup page sends you to your GitHub to create the private GitHub App in your organization, and to install it there. On GitHub Enterprise Server, the App’s page is under /github-apps/ instead of /apps/.

Terraform / OpenTofu#

Set github_enterprise_url:

module "runs_on_flex" {
  source  = "runs-on/runs-on/aws//modules/flex"
  version = "v3.5.0"

  github_organization   = "my-org"
  github_enterprise_url = "https://github.example.com"

  # license_key, email, vpc_id and subnets as in the Flex install guide
}

Fleet#

Set github_base_url to your GitHub’s URL, then create the credential on your GitHub instead of github.com. The Fleet install guide gives a link for each one: replace https://github.com in it with your URL.

• Organization mode: a GitHub App in your organization, with webhooks off.
• Enterprise mode: a classic personal access token with the manage_runners:enterprise scope, passed as github_enterprise_pat, and your enterprise slug as github_enterprise_name. Fleet registers enterprise runners, and enterprise runner groups decide which organizations use them.

module "runs_on_fleet" {
  source  = "runs-on/runs-on/aws//modules/fleet"
  version = "v3.5.0"

  github_base_url        = "https://github.example.com"
  github_enterprise_pat  = var.github_enterprise_pat
  github_enterprise_name = "my-enterprise"

  # license_key, email, VPC, runners and fleets as in the Fleet install guide
}

If you manage runner groups with the integrations/github Terraform provider, point its base_url ↗ at your GitHub too, on GHE.com as on GitHub Enterprise Server. For a server, that is its URL with a trailing slash, such as https://github.example.com/.

RunsOn actions on GitHub Enterprise Server#

Several features run through runs-on/action@v2 ↗, which is hosted on github.com: Magic Cache, sticky-disk cache modes and the sccache integration among them.

On GitHub Enterprise Server, workflows can use an action from github.com only once a site admin makes it available, in one of two ways:

• Turn on automatic access to GitHub.com actions with GitHub Connect ↗.
• Sync runs-on/action to the server with actions-sync ↗. Sync runs-on/snapshot too if your workflows still use it.

Jobs run on RunsOn without the action. The features that need it are then unavailable.

On GHE.com, workflows use actions from github.com directly.

Networking#

• Flex receives jobs as webhooks on the stack’s public HTTPS endpoint. Your GitHub must be able to reach it.
• Fleet only makes outbound connections: it pulls jobs from GitHub, so your GitHub never connects to AWS.
• Both call your GitHub’s API from AWS, download GitHub’s runner releases from github.com, and send the license check and one event per job to runs-on.com. Runner releases come through the hosts GitHub lists for self-hosted runners ↗, such as api.github.com and its release-asset hosts. What RunsOn receives lists every field.

EnableWAF limits Flex’s endpoint to github.com’s webhook IP ranges, so it only works with github.com. The stack rejects EnableWAF=true when GithubEnterpriseUrl is set. With Terraform, enable_waf = true needs your own web ACL in public_ingress_web_acl_arn.

What differs from github.com#

On GitHub Enterprise Server, the runner’s own GITHUB_SERVER_URL and GITHUB_API_URL apply. The Git cache speeds up fetches from github.com only. Everything else, from job labels and runner images to Spot, sticky disks and cost reports, works the same on all three.