GitHub Actions integration for Orka

The Orka GitHub runner provisions ephemeral macOS runners for GitHub Actions as Orka VMs. Runners scale up when jobs are queued and are torn down afterward, so you’re not paying for idle VMs between builds and every job starts from a known, clean image. The runner authenticates to GitHub as a GitHub App (or, for enterprise-level registration, a personal access token) and to Orka with a service account token. It runs as a standalone container, not a Jenkins-style plugin, so you deploy it as a long-running process with connectivity to both GitHub and your Orka cluster. New to Orka? See how teams use it for CI/CD.

This integration releases independently of Orka and is compatible with Orka 3.x. Check the releases page for the current version.

Prerequisites

Have all of these in place before step 1.

Requirement	Notes
Orka 3.0+ cluster	Access managed through the MacStadium Customer Portal. See Cluster Access Management.
Network path from the runner host to Orka	The machine running the Orka GitHub runner needs connectivity to the Orka cluster, including SSH access to deployed VMs. Use a VPN client to test, or a site-to-site tunnel (AWS, GCP) for production.
Your Orka API URL	From the IP Allocation table in My Cloud.
Orka3 CLI	Download and install, then run `orka3 config set --api-url <ORKA_API_URL>`.
A GitHub App (or a classic PAT for enterprise-level runners)	See Creating a GitHub App. Enterprise-level registration can’t use a GitHub App. GitHub doesn’t grant App installations the `manage_runners:enterprise` permission, so it needs a classic PAT with `admin:enterprise` scope instead.
Docker	The runner ships as a container image, `ghcr.io/macstadium/orka-github-runner`.

Setup steps

1. Create a service account and VM config

orka3 sa create github-runner
orka3 sa token github-runner

orka3 vmc create my-runner-config --image <IMAGE_NAME>

Save the token from the first command and the VM config name for step 3.

2. Set up your GitHub App

Follow Creating a GitHub App and note the App ID, installation ID, and private key. If you’re registering at the enterprise level instead, skip this and use a classic PAT with the admin:enterprise scope. Use a dedicated service account for it and rotate it on a schedule, since it’s long-lived and broadly privileged.

3. Configure environment variables

At minimum you need GitHub auth, GITHUB_URL, ORKA_URL, ORKA_TOKEN, ORKA_VM_CONFIG, and a RUNNERS definition:

GITHUB_APP_ID=<GITHUB_APP_ID>
GITHUB_APP_INSTALLATION_ID=<INSTALLATION_ID>
GITHUB_APP_PRIVATE_KEY_PATH=/secrets/github-app.pem
GITHUB_URL=https://github.com/<ORG_OR_REPO>
ORKA_URL=<ORKA_API_URL>
ORKA_TOKEN=<ORKA_TOKEN>
ORKA_VM_CONFIG=my-runner-config
RUNNERS='[{"name":"my-github-runner","id":1}]'

The name in RUNNERS must match the runs-on label your workflows target. GITHUB_APP_PRIVATE_KEY_PATH is read inside the container, so it’s the path you mount the key to in step 4 (/secrets/github-app.pem in these examples), not the key’s location on your host. See the full variable reference below, and an example .env file here.

The GitHub App private key must be PKCS#1 RSA format. If your key doesn’t work, convert it with ssh-keygen -p -m pem -f <PATH_TO_KEY>.

4. Run the container

Either pass environment variables directly:

docker run -v <PATH_TO_KEY>:/secrets/github-app.pem:ro -e GITHUB_APP_ID=<GITHUB_APP_ID> -e GITHUB_APP_INSTALLATION_ID=<INSTALLATION_ID> -e GITHUB_APP_PRIVATE_KEY_PATH=/secrets/github-app.pem -e GITHUB_URL=https://github.com/<ORG_OR_REPO> -e ORKA_URL=<ORKA_API_URL> -e ORKA_TOKEN=<ORKA_TOKEN> -e ORKA_VM_CONFIG=my-runner-config -e RUNNERS='[{"name":"my-github-runner","id":1}]' ghcr.io/macstadium/orka-github-runner:<TAG>

Or mount a .env file:

docker run -v <PATH_TO_ENV_FILE>:/.env -v <PATH_TO_KEY>:/secrets/github-app.pem:ro ghcr.io/macstadium/orka-github-runner:<TAG>

If you’re running this inside MacStadium, 2 vCPU / 15GB of Private Cloud x86 compute is enough to host the container itself, billed as part of your VPC services.

5. Run a test workflow

Point a workflow at the runner label from your RUNNERS config:

jobs:
  build:
    runs-on: my-github-runner
    steps:
      - run: sw_vers && xcodebuild -version

A successful run confirms the whole chain: GitHub auth, Orka connectivity, VM deployment, and job pickup.

Configuration reference

GitHub authentication

Variable	Default	Notes
`GITHUB_APP_ID`	none	Required unless `GITHUB_PAT` is set.
`GITHUB_APP_INSTALLATION_ID`	none	Required unless `GITHUB_PAT` is set.
`GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY`	none	File path or literal key string. One is required unless `GITHUB_PAT` is set.
`GITHUB_PAT`	none	Classic PAT, used instead of App auth. Required for enterprise-level runners. Takes precedence over the App variables when set.
`GITHUB_URL`	none	Repository, organization, or enterprise URL.
`GITHUB_API_URL`	derived from `GITHUB_URL`	Deprecated and ignored. Setting it logs a warning.
`GITHUB_TOKEN`	none	Optional github.com token used only to look up the latest runner release, to avoid the 60 requests/hour unauthenticated rate limit. Not needed if `GITHUB_RUNNER_VERSION` is pinned.
`GITHUB_RUNNER_VERSION`	latest, looked up at startup	Pins the Actions runner version deployed to each VM, for example `2.336.0` (no leading `v`).

Orka connection

Variable	Default	Notes
`ORKA_URL`	none	Your Orka API URL.
`ORKA_NAMESPACE`	`orka-default`	Namespace for deployed VMs.
`ORKA_TOKEN`	none	Service account token, from `orka3 sa token <SERVICE_ACCOUNT_NAME>`.
`ORKA_VM_CONFIG`	none	VM config name, from `orka3 vmc create <VM_CONFIGURATION_NAME> --image <IMAGE_NAME>`.
`ORKA_VM_USERNAME`	`admin`
`ORKA_VM_PASSWORD`	`admin`
`ORKA_VM_METADATA`	none	Custom VM metadata, `key=value` comma-separated.
`ORKA_ENABLE_NODE_IP_MAPPING`	`false`	Enables mapping Orka node internal IPs to external host IPs.
`ORKA_NODE_IP_MAPPING`	none	The internal-to-external IP mapping itself.

Runner behavior

Variable	Default	Notes
`RUNNERS`	none	JSON array defining the runner scale set, for example `[{"name":"my-github-runner","id":1}]`. Only one scale set per running instance. See multiple runners below.
`MANAGE_RUNNER_SCALE_SETS`	`false`	When `true`, deletes any existing scale set with the same name on startup and deletes it again on exit. When `false`, reuses an existing scale set if found and skips deletion on exit.
`ENABLE_RECONCILIATION`	`true`	On startup, inspects existing Orka VMs for the scale set and adopts, cleans up, or deletes each one, so the runner can recover from a prior process exit.
`MAX_RUNNERS`	`9000`	Ceiling reported to GitHub for the scale set.
`VM_TRACKER_INTERVAL`	`300s`	How often orphaned VMs are checked for. A VM is deleted after two consecutive checks with no corresponding GitHub runner.
`RUNNER_DEREGISTRATION_TIMEOUT`	`30s`	How long to wait for a runner to cleanly de-register from GitHub before force-deleting it.
`RUNNER_DEREGISTRATION_POLL_INTERVAL`	`2s`	How often to poll GitHub while waiting for de-registration.
`LOG_LEVEL`	`info`	`debug`, `info`, or `error`.

Metrics (optional)

Variable	Default	Notes
`ENABLE_METRICS`	`false`	Exposes Prometheus metrics at `/metrics` when `true`.
`METRICS_ADDR`	`:8080`	Address the metrics endpoint listens on.
`METRICS_POLL_INTERVAL`	`30s`	How often runner scale set statistics are polled.

GitHub Enterprise Server (GHES)

Set GITHUB_URL to your enterprise instance (for example https://github.enterprise.com/my-org), and provide either a GITHUB_TOKEN with permission to pull the runner release from github.com, or pin GITHUB_RUNNER_VERSION to avoid contacting github.com at startup entirely. GHES is detected automatically from GITHUB_URL.

Multiple runners

Only one runner scale set is supported per running instance. For multiple scale sets, run multiple instances of the container, each with its own RUNNERS value and a unique runner name.

Beyond a single runner pool

A few things worth knowing about as your usage grows:

Observability. Set ENABLE_METRICS=true to get Prometheus metrics on scale-set state (available jobs, busy/idle runners) at METRICS_ADDR, useful for building dashboards or alerts on top of your runner fleet rather than guessing at capacity.
Custom VM images. ORKA_VM_CONFIG points at any VM config you’ve created with orka3 vmc create, so you’re not limited to a base image. Build one with your own tooling pre-installed to cut per-job setup time.
Image caching. If cold starts on a new image are slow, see Image Caching to pre-cache images on specific nodes ahead of time.
Burst capacity. If your fixed node pool isn’t enough during peak build periods, Orka Burst adds on-demand elastic capacity without a long-term hardware commitment.

Troubleshooting

Symptom	Likely cause	Fix
Startup fails with `403 Forbidden` while looking up the runner version	Unauthenticated `GITHUB_TOKEN` lookups are capped at 60 requests/hour per IP, and that limit was hit.	Set `GITHUB_TOKEN`, or pin `GITHUB_RUNNER_VERSION` to skip the lookup entirely.
Enterprise-level registration fails with `403 Resource not accessible by integration`	GitHub doesn’t grant App installations the `manage_runners:enterprise` permission. This is a GitHub platform limitation, not specific to this runner.	Use a classic PAT with `admin:enterprise` scope via `GITHUB_PAT` instead of App auth for enterprise-level runners.
GitHub App authentication fails even though the App ID and installation ID look correct	The private key isn’t in PKCS#1 RSA format.	Convert it with `ssh-keygen -p -m pem -f <PATH_TO_KEY>`.
VMs pile up in Orka after the runner container restarts or crashes	`ENABLE_RECONCILIATION` (default `true`) should adopt or clean these up on the next startup; orphans that aren’t part of a live scale set are removed after two `VM_TRACKER_INTERVAL` checks (default 300s each).	Give it a couple of tracker intervals before assuming it’s stuck. If VMs are still stuck after that, check the container logs at `LOG_LEVEL=debug`.
Runner labeled correctly in `RUNNERS`, but jobs never pick it up	The `name` in `RUNNERS` doesn’t match the workflow’s `runs-on` value.	Confirm the two match exactly, including case.

Support

Open a ticket in the MacStadium Portal and include the runner container’s logs (LOG_LEVEL=debug if possible).

MacStadium

Orka

MacStadium VDI

IaaS

GitHub Actions integration for Orka

Prerequisites

Setup steps

1. Create a service account and VM config

2. Set up your GitHub App

3. Configure environment variables

4. Run the container

5. Run a test workflow

Configuration reference

GitHub authentication

Orka connection

Runner behavior

Metrics (optional)

GitHub Enterprise Server (GHES)

Multiple runners

Beyond a single runner pool

Troubleshooting

Support

​Prerequisites

​Setup steps

​1. Create a service account and VM config

​2. Set up your GitHub App

​3. Configure environment variables

​4. Run the container

​5. Run a test workflow

​Configuration reference

​GitHub authentication

​Orka connection

​Runner behavior

​Metrics (optional)

​GitHub Enterprise Server (GHES)

​Multiple runners

​Beyond a single runner pool

​Troubleshooting

​Support

Prerequisites

Setup steps

1. Create a service account and VM config

2. Set up your GitHub App

3. Configure environment variables

4. Run the container

5. Run a test workflow

Configuration reference

GitHub authentication

Orka connection

Runner behavior

Metrics (optional)

GitHub Enterprise Server (GHES)

Multiple runners

Beyond a single runner pool

Troubleshooting

Support