Skip to content

Update documentation to match the current environment variables #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
existemi merged 2 commits into from
Aug 20, 2026
Merged

Update documentation to match the current environment variables #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
33e4298
Update documentation
existemi Aug 18, 2026
d3fa784
comment out default env values
existemi Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,15 @@ Before using the Orka GitHub Runner, ensure that the following prerequisites are

### GitHub Enterprise Server

The Orka GitHub Runner now supports GitHub Enterprise Server (GHES) environments. To use the runner with GHES, you'll need to provide the following additional environment variables:

* `GITHUB_API_URL`: The URL of your GitHub Enterprise Server API endpoint (e.g., `https://github.enterprise.com/api/v3`)
* `GITHUB_TOKEN`: A GitHub token with appropriate permissions to avoid rate limiting
The Orka GitHub Runner supports GitHub Enterprise Server (GHES) environments.

When using GHES, make sure to:
1. Configure the `GITHUB_URL` to point to your enterprise instance (e.g., `https://github.enterprise.com`)
2. Set the `GITHUB_API_URL` to your enterprise API endpoint
3. Provide a valid `GITHUB_TOKEN` with appropriate permissions for pulling the runner from github.com
1. Configure the `GITHUB_URL` to point to your organization or repository on your enterprise instance (e.g., `https://github.enterprise.com/my-org`)
2. Provide a valid `GITHUB_TOKEN` with appropriate permissions for pulling the runner from github.com, or pin `GITHUB_RUNNER_VERSION` to avoid contacting github.com at startup entirely

The API endpoint is derived from `GITHUB_URL` and is logged on startup, so it does not need to be configured. `GITHUB_API_URL` is accepted but ignored, and the runner logs a warning when it is set.

The runner will automatically detect if you're using GHES based on the provided URLs and adjust its behavior accordingly.
The runner will automatically detect if you're using GHES based on the provided URL and adjust its behavior accordingly.

### Enterprise-level runners

Expand All @@ -59,9 +57,11 @@ The Orka GitHub runner requires the following environment variabales to be confi
* `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY`: The private key associated with the GitHub App. You can either provide the file path to the private key using `GITHUB_APP_PRIVATE_KEY_PATH` or directly provide the private key string using `GITHUB_APP_PRIVATE_KEY`. At least one of these environment variables must be set. Not required when `GITHUB_PAT` is set.
* `GITHUB_PAT`: (Optional) A classic personal access token used instead of GitHub App authentication. Required for enterprise-level runners, where GitHub App authentication is not supported — see [Enterprise-level runners](#enterprise-level-runners). When set, it takes precedence over the GitHub App variables.
* `GITHUB_URL`: The URL of the GitHub repository, organization, or enterprise.
* `GITHUB_API_URL`: (Optional) The URL of the GitHub API endpoint. If not provided, it will default to github.com api endpoint if Github URL starts with "https://github.com" otherwise defaults to "<GITHUB_URL>/api/v3"
* `GITHUB_TOKEN`: (Optional) A GitHub token to avoid rate limiting. Required for GitHub Enterprise Server.
* `GITHUB_API_URL`: (Deprecated, ignored) The API URL is derived from `GITHUB_URL` and logged on startup. Setting this variable has no effect and logs a warning.
* `GITHUB_TOKEN`: (Optional) A github.com token used only to look up the latest runner release, to avoid rate limiting. This is always a github.com token, even on GHES, and is unrelated to `GITHUB_PAT`. Unauthenticated lookups are limited to 60 requests per hour per IP, and exceeding that fails startup with `403 Forbidden`. Not needed if `GITHUB_RUNNER_VERSION` is set.
* `GITHUB_RUNNER_VERSION`: (Optional) Pins the GitHub Actions runner version deployed to each VM, for example `2.336.0`. Must not include a leading `v`. If not provided, the latest release is looked up from github.com at startup, which requires outbound access to `api.github.com`.
* `ORKA_URL`: The URL of the Orka server.
* `ORKA_NAMESPACE`: (Optional) The Orka namespace used when deploying VMs. Defaults to `orka-default`.
* `ORKA_TOKEN`: The authentication token for accessing the Orka API. A token can be generated by an admin user with the command `orka3 sa token <service-account-name>`.
* `ORKA_VM_CONFIG`: The name of the VM config that will be used when deploying Orka virtual machines. A config can be created with the command `orka3 vmc create --image <image-name>`.
* `ORKA_VM_USERNAME`: Specifies the username for the deployed VMs. If no value is provided, it defaults to admin.
Expand All @@ -75,6 +75,11 @@ The Orka GitHub runner requires the following environment variabales to be confi
* `METRICS_ADDR`: (Optional) The address where the Prometheus metrics endpoint will be exposed (e.g., `:8080`). Defaults to `:8080`.
* `METRICS_POLL_INTERVAL`: (Optional) Interval at which runner scale set statistics are polled and metrics are updated (e.g., `30s`, `1m`). Defaults to `30s`.
* `MANAGE_RUNNER_SCALE_SETS`: (Optional) When set to `true`, deletes any existing runner scale set with the same name on startup and deletes the scale set on exit. When set to `false`, reuses an existing scale set if found and skips deletion on exit. Defaults to `false`.
* `MAX_RUNNERS`: (Optional) The maximum number of runners the scale set will report to GitHub. Defaults to `9000`.
* `ENABLE_RECONCILIATION`: (Optional) When set to `true`, on startup the runner inspects existing Orka VMs for the scale set and adopts, cleans up, or deletes each one so it can recover from a prior process exit. Defaults to `true`.
* `VM_TRACKER_INTERVAL`: (Optional) Interval at which orphaned VMs are checked for. A VM is deleted after two consecutive checks without a corresponding GitHub runner. Defaults to `300s`.
* `RUNNER_DEREGISTRATION_TIMEOUT`: (Optional) How long to wait for a runner to cleanly de-register from GitHub before force-deleting it. Defaults to `30s`.
* `RUNNER_DEREGISTRATION_POLL_INTERVAL`: (Optional) How often to poll GitHub while waiting for a runner to de-register. Defaults to `2s`.

For a complete example of the required format, refer to the `.env` file located in the examples directory [here](./examples/.env).

Expand Down
5 changes: 5 additions & 0 deletions docs/github-app-setup-steps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Creating a GitHub app

> **NOTE**: GitHub App authentication covers repository-level and organization-level runners only.
> Runners registered at the enterprise level must use a personal access token instead, because
> GitHub does not grant the `manage_runners:enterprise` permission to App installations. See
> [Enterprise-level runners](../README.md#enterprise-level-runners).

## Setup steps

* Choose App Creation Method: Decide whether to create the app for your user account or an organization.
Expand Down
44 changes: 36 additions & 8 deletions examples/.env
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,30 @@ GITHUB_PAT=""
# GITHUB_URL="https://<my-enterprise-github-url>/enterprises/<enterprise-name>" which requires GITHUB_PAT
GITHUB_URL="https://github.com/macstadium"

# [Optional] Used to customize the API endpoint used for interacting with Github,
# if not provided and the GITHUB_URL starts with "https://github.com" it will by default be "https://api.github.com"
# otherwise if GITHUB_URL is something else it will assume GHES and use "<GITHUB_URL>/api/v3"
# example setting for GHES "https://<my-enterprise-github-url>/api/v3"
GITHUB_API_URL="https://api.github.com"

# [Optional] GITHUB_TOKEN if provided is used to provide a PAT token that has authorization to
# pull the latest runner image from github.com, this is primarily used to avoid rate-limiting.
# [Deprecated, ignored] GITHUB_API_URL is no longer used. The API endpoint is derived from
# GITHUB_URL and logged on startup. Setting this variable has no effect and logs a warning.
# GITHUB_API_URL=""

# [Optional] GITHUB_TOKEN is a github.com token used only to look up the latest runner release,
# primarily to avoid rate-limiting. It is always a github.com token, even on GHES, and is
# unrelated to GITHUB_PAT. Unauthenticated lookups are limited to 60 requests per hour per IP,
# and exceeding that fails startup with "403 Forbidden".
# Not needed if GITHUB_RUNNER_VERSION is set.
GITHUB_TOKEN=""

# [Optional] GITHUB_RUNNER_VERSION pins the GitHub Actions runner version deployed to each VM.
# Must not include a leading "v". If unset, the latest release is looked up from api.github.com
# at startup, which requires outbound access to github.com. Leave unset unless you need to pin,
# since a pinned version does not track new runner releases.
# GITHUB_RUNNER_VERSION="2.336.0"

# [Required] ORKA_URL specifies the API endpoint for the Orka. Obtain this information from your IP plan.
ORKA_URL="http://10.221.188.20"

# [Optional] ORKA_NAMESPACE specifies the Orka namespace used when deploying VMs.
# If not provided, it defaults to "orka-default".
# ORKA_NAMESPACE="orka-default"

# [Required] ORKA_TOKEN should be set to a valid JWT service account token for accessing the Orka service.
# The token can be generated by an admin user using the command 'orka3 sa token <service-account-name>'.
ORKA_TOKEN=""
Expand All @@ -58,6 +69,11 @@ ORKA_TOKEN=""
# The config can be created using the command 'orka3 vmc create --image <image-name>'.
ORKA_VM_CONFIG="my-orka-runner"

# [Optional] ORKA_VM_USERNAME and ORKA_VM_PASSWORD specify the credentials used to connect to the
# deployed VMs over SSH. If not provided, both default to "admin".
# ORKA_VM_USERNAME="admin"
# ORKA_VM_PASSWORD="admin"

# [Optional] Allow the usage of the public IPs
ORKA_ENABLE_NODE_IP_MAPPING=true

Expand Down Expand Up @@ -87,6 +103,18 @@ ORKA_VM_METADATA="key1=value1,key2=value2"
# If not provided, it defaults to 300 seconds.
VM_TRACKER_INTERVAL="300s"

# [Optional] RUNNER_DEREGISTRATION_TIMEOUT is how long to wait for a runner to cleanly de-register
# from GitHub before force-deleting it. If not provided, it defaults to 30 seconds.
# RUNNER_DEREGISTRATION_TIMEOUT="30s"

# [Optional] RUNNER_DEREGISTRATION_POLL_INTERVAL is how often to poll GitHub while waiting for a
# runner to de-register. If not provided, it defaults to 2 seconds.
# RUNNER_DEREGISTRATION_POLL_INTERVAL="2s"

# [Optional] MAX_RUNNERS is the maximum number of runners the scale set will report to GitHub.
# If not provided, it defaults to 9000.
# MAX_RUNNERS=9000

# Prometheus metrics (optional)
ENABLE_METRICS=true
METRICS_ADDR=:8080
Expand Down
Loading