From 33e429808fc868b0a2c97ab57fb0ddcb85848ffb Mon Sep 17 00:00:00 2001 From: Roy Larsen Date: Tue, 18 Aug 2026 17:28:18 -0400 Subject: [PATCH 1/2] Update documentation --- README.md | 25 ++++++++++++-------- docs/github-app-setup-steps.md | 5 ++++ examples/.env | 43 +++++++++++++++++++++++++++------- 3 files changed, 55 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index b2a98d1..67d885b 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 "/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 `. * `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 `. * `ORKA_VM_USERNAME`: Specifies the username for the deployed VMs. If no value is provided, it defaults to admin. @@ -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). diff --git a/docs/github-app-setup-steps.md b/docs/github-app-setup-steps.md index 0587537..75bde52 100644 --- a/docs/github-app-setup-steps.md +++ b/docs/github-app-setup-steps.md @@ -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. diff --git a/examples/.env b/examples/.env index 7d590eb..38f8ebc 100644 --- a/examples/.env +++ b/examples/.env @@ -36,19 +36,29 @@ GITHUB_PAT="" # GITHUB_URL="https:///enterprises/" 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 "/api/v3" -# example setting for GHES "https:///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. +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 '. ORKA_TOKEN="" @@ -58,6 +68,11 @@ ORKA_TOKEN="" # The config can be created using the command 'orka3 vmc create --image '. 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 @@ -87,6 +102,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 From d3fa7848a6a5d1831d7a1d436a092c3313606b43 Mon Sep 17 00:00:00 2001 From: Roy Larsen Date: Wed, 19 Aug 2026 12:54:15 -0400 Subject: [PATCH 2/2] comment out default env values --- examples/.env | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/examples/.env b/examples/.env index 38f8ebc..6749168 100644 --- a/examples/.env +++ b/examples/.env @@ -49,15 +49,16 @@ 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. -GITHUB_RUNNER_VERSION="2.336.0" +# 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" +# 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 '. @@ -70,8 +71,8 @@ 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" +# ORKA_VM_USERNAME="admin" +# ORKA_VM_PASSWORD="admin" # [Optional] Allow the usage of the public IPs ORKA_ENABLE_NODE_IP_MAPPING=true @@ -104,15 +105,15 @@ 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" +# 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" +# 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 +# MAX_RUNNERS=9000 # Prometheus metrics (optional) ENABLE_METRICS=true