This project is no longer actively maintained.

We recommend migrating to Actions Runner Controller (ARC), the official self-hosted runner solution maintained by GitHub. ARC provides Kubernetes-native autoscaling, scale-to-zero, and active maintenance from the GitHub community.

For more information, see the official documentation.

The existing container images in this repository remain available for current deployments, but they will not receive new features or regular updates.

OpenShift GitHub Actions Runners

This repository contains Containerfiles for building container images that act as self-hosted GitHub Action runners that work on OpenShift.

The OpenShift Actions Runner Chart is used to deploy these images into a cluster, and the OpenShift Actions Runner Installer is an Action to automate the chart install.

Runners

1. The base runner is based on Fedora. It is intended to have a fairly minimal tool set to keep the image size as small as possible. It has all the GitHub Actions Runner needs, plus a limited number of popular Unix command-line tools.
2. The buildah runner extends the base runner to add buildah and podman. This runner requires permissions that are disabled for by default on OpenShift. See the buildah image README for details.
3. The K8s tools runner installs a set of CLIs used to work with Kubernetes.
4. The Node.js runner includes a Node.js runtime.
5. The Java runner includes a JDK and JRE.
6. The .NET runner includes the .NET 10 SDK.

The idea is that the base runner can be extended to build larger, more complex images that have additional capabilities. Refer to Creating your own runner image.

The images are hosted at quay.io/redhat-github-actions.

While these images are developed for and tested on OpenShift, they do not contain any OpenShift specific code and should be compatible with any Kubernetes platform.

Installing into a cluster

Use the OpenShift Actions Runner Chart to deploy these runners into your cluster.

Creating a Personal Access Token

To register themselves with GitHub, the runners require a GitHub Personal Access Token (PAT) which has the repo permission scope. This is provided to the container through the GITHUB_PAT environment variable.

• The user who created the token must have administrator permission on the organization/repository the runner will be added to.
• If the runner will be for an organization, the token must also have the admin:org permission scope.
• See an example.

Building your own runner image

See the base image README.

Running Locally

You can run the images locally to test and develop.

To launch and connect a runner to redhat-actions/openshift-actions-runners with the labels local and podman:

podman run \
    --env GITHUB_PAT=$GITHUB_PAT \
    --env GITHUB_OWNER=redhat-actions \
    --env GITHUB_REPOSITORY=openshift-actions-runners \
    --env RUNNER_LABELS="local,podman" \
    quay.io/redhat-github-actions/runner:latest

Or, to run a shell for debugging:

podman run -it --entrypoint=/bin/bash quay.io/redhat-github-actions/runner:latest

Authenticating with a Runner Token

A Runner Token can be used as an alternative to PAT or GitHub App authentication.

Refer to Authenticating with a Runner Token.

Running with Github App Authentication

If you are able to use a GitHub App it is highly recommended over the PAT because you have greater control of the API permissions granted to it and you do not need a bot or service account.

Refer to Authenticating with GitHub App Authentication.

GitHub Enterprise Support

You can use any of the runners on your GitHub Enterprise server by overriding GITHUB_DOMAIN in the environment, using podman run --env or using the chart.

For example, if you set:

GITHUB_DOMAIN=github.mycompany.com

the runner entrypoint will then try and register itself with

https://github.mycompany.com/$GITHUB_OWNER/$GITHUB_REPOSITORY

and use the GitHub API at

https://github.mycompany.com/api/v3/

Custom CA Certificates

If your GitHub Enterprise server uses a self-signed certificate, set the CUSTOM_CA_CERT environment variable to the path of your CA certificate file inside the container. This configures both curl (for runner registration) and Node.js (for the runner process) to trust the certificate.

podman run \
    --env GITHUB_PAT=$GITHUB_PAT \
    --env GITHUB_OWNER=myorg \
    --env GITHUB_DOMAIN=github.mycompany.com \
    --env CUSTOM_CA_CERT=/certs/ca.crt \
    -v /path/to/ca.crt:/certs/ca.crt:ro \
    quay.io/redhat-github-actions/runner:latest

Troubleshooting

If the containers crash on startup, it is usually because one of the environment variables is missing or misconfigured. Make sure to read the container logs carefully to make sure the variables' values are set as expected.

• If the container crashes with an HTTP 403 error, the GITHUB_PAT does not have the appropriate permissions. Refer to the PAT guidelines.
• If the container crashes with an HTTP 404 error, the GITHUB_OWNER or GITHUB_REPOSITORY is incorrect or misspelled.
  • This will also happen if a private repository is selected which the GITHUB_PAT does not have permission to view.

If you encounter any other issues, please open an issue and we will help you work through it.

Credits

This repository builds on the work done in bbrowning/github-runner, which is forked from SanderKnape/github-runner.

The Github App creation tutorial is heavily based on the excellent README in actions-runner-controller/actions-runner-controller