Actions Runner Manager is a GitHub Application that can be used by users who are not organization owners to manage GitHub Actions Organization Runner Groups. Actions Runner Manager implements pseudo-RBAC policies built on top of GitHub Teams and exposes a set of authenticated API's to grant access to the GitHub Organization Self-Hosted Runner REST API's which are generally only available to organization owners.
Notice: Actions Runner Manager does not currently support GitHub Enterprise Server
Actions Runner Manager uses existing GitHub Teams to create a pseudo-RBAC policy. Every call requires a user to submit a valid GitHub API token
assigned to a user who is a maintainer of a GitHub Team in the Authorization header.
Notice: Only users who are maintainers of a GitHub Team may use the Actions Runner Manager API's.
When a user makes a request to any of the Actions Runner Manager API's, the team parameter is used as the name of the
Runner Group. When a user calls /group-create or /group-delete, an Organization Runner Group is created or deleted
with the name specified in the team parameter. All other API endpoints query or delete assets from the Organization
Runner Group assigned to the team parameter.
When a user submits a valid GitHub API token to the Actions Runner Manager API's, the application first creates an
authorized GitHub client using the users GitHub API token. The API then makes an authenticated API call as the
user to the /user GitHub API endpoint documented here: https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
This call returns the GitHub Users object of which the only information retrieved is the users login property. This
property is the GitHub username of the authenticated user. This data is passed to the Teams API to confirm the user
making the request on the Actions Runner Manager API is a maintainer of the GitHub Team. The users API token is not used
for any other purpose. The username is also stored in the rate limit cache for 60 minutes to enforce our rate limit
policies on the server. If the user has not made an authenticated API call in the past 60 minutes, the rate limit cache
purges the username of the authenticated user.
Note: While the Actions Runner Manager API's make secure, limited use of the users object, and does not call any other API endpoints while authenticated as the user, users should be sensitive to the fact that the Users API returns private Personally Identifiable Information (PII) such as email addresses. As such, we recommend users use bot accounts tightly scoped to only the Teams they need access to in order to limit risk and exposure.
To protect the integrity of the server, Actions Runner Manager uses a rate limit cache to enforce an admin configured rate limit policy. The rate limit cache is purged every 60 minutes. The rate limit setting defines the maximum number of authenticated requests a user can make per second. If you encounter a rate limit error, you should wait a few seconds and attempt your request again.
To configure the Actions Runner Manager, you must create and install a GitHub App. The app must be configured with the following permissions:
Repository:
Metadata: Read-Only
Organization:
Members: Read-Only
Administration: Read and Write
Self-Hosted Runners: Read and Write
Note: The Actions Runner Manager does not currently make use of Webhooks or Callbacks, you may leave these options blank when creating the GitHub Application.
Once you have created a GitHub App, you must install the application in your organization and give it permission to the repositories you want it to be able to assign runner groups to.
You can follow GitHub's documentation on how to create and install a GitHub App here:
The Actions Manager reads a static YAML file to create its configuration. By default, the config file is read from the
directory in which the application is run from with a file name of config.yml. Users can override the default path by
setting the CONFIG_PATH environment variable, for example: export CONFIG_PATH=/opt/arm/config.yml.
The configuration file is a YAML file with the following structure:
org: "<GitHub Organization>"
appID: <GitHub Application ID>
installationID: <GitHub Application Installation ID>
privateKey: "<Base64 Encoded GitHub Application Private Key>"
logging:
compress: (true or false) <Compress rotated log files>
ephemeral: (true or false) <Log to stdout instead of rotating log files>
level: (debug, info, warn, error, or fatal) <Logging level>
logDirectory: <Relative or absolut directory to log to>
maxAge: <Maximum number of days to keep log files>
maxBackups: <Maximum number of log files to keep>
maxSize: <Maximum size of log files in bytes before rotation>
server:
address: "<IP Address or Hostname bind interface>"
port: <Port to bind to>
rateLimit: <Maximum number of authenticated requests a user can make per second>
tls:
enabled: (true or false) <Enable TLS>
certFile: "<Path to TLS certificate file>"
keyFile: "<Path to TLS key file>"Note: You can encode your private key into Base64 by using the following command after downloading it from the GitHub UI:
cat <private_key_file> | base64Security Notice: Actions Runner Manager should never run in non-TLS mode when in production. Users should configure TLS on the server directly or use some form of software or hardware to enforce TLS.
Download the current binary from: https://github.com/lindluni/actions-runner-manager/releases
or
Build the current binary using the Go toolchain:
go install github.com/lindluni/actions-runner-manager/pkgThen create a config file according to the documentation above, then run the binary with the following command:
actions-runner-managerIt is recommended you use a Service Manager such as systemd to ensure the server is running.
Actions Runner Manager hosts its image on the GitHub Container Registry. You must first authenticate using a GitHub API token to pull the image using the following command:
docker login -u <GitHub Username> -p <GitHub API Token> ghcr.ioCreate a config file according to the documentation above, then run the following command:
docker run -it -d --restart always \
-v <absolute_path_to_config_file>:/<config.yml> \
-p <local port>:<port set in config> \
ghcr.io/lindluni/actions-runner-manager:latestTO BE COMPLETED
You can find detailed API documentation on our GitHub Page
Actions Runner Manager implements the following API's:
- Create a new GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/group-add?team=<team_slug>"- Delete an existing GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/group-delete?team=<team_slug>"- List all the runners and repositories assigned to a GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/group-list?team=<team_slug>"- Add one or more repositories to an existing GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/repos-add?team=<team_slug>&repos=<repo1>,<repo2>,<repo3>"- Remove one or more repositories from an existing GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/repos-remove?team=<team_slug>&repos=<repo1>,<repo2>,<repo3>"- Replace all existing repositories assigned to an existing GitHub Actions Runner Group with the name in the
teamparameter with one or more new repositories
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/repos-set?team=<team_slug>&repos=<repo1>,<repo2>,<repo3>"- Create a new Registration Token to be used during runner configuration to register a runner to an existing GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/token-register?team=<team_slug>"- Create a new Removal Token to be used during runner de-provisioning to remove a runner from an existing GitHub Actions Organization Runner Group with the name in the
teamparameter
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/token-remove?team=<team_slug>"- Checks the readiness status of the server
curl -H "Authorization: <token>" "https://<host>:<port>/api/v1/status"The Google Distroless containers provide a simple, secure, and scalable way to run Docker containers. The Distroless image is a small base image and contains no executables or shell other than the Actions Runner Manager and its dependencies. As such, it is ultra secure as it contains no extraneous dependencies requiring being kept up to date and potentially exposing the application API's to outside vulnerabilities.
The major caveat of the Distroless container is that it contains no shell, thus making it more secure, but as such, it cannot be exec'ed into. If you require a shell, you must modify the Dockerfile to use a different base image for the final container.
You can read up on the Google Distroless base image at the links below: