chetansha256/openshift-actions-runners

GitHub Action self-hosted runner images for OpenShift.

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.

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-runner with the labels local and podman:

podman run \
    --env GITHUB_PAT=$GITHUB_PAT \
    --env GITHUB_OWNER=redhat-actions \
    --env GITHUB_REPOSITORY=openshift-actions-runner \
    --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

Running Locally without PAT

If you're not comfortable persisting a PAT with access to all of your repositories, it is also possible to manually generate a runner registration token and use that.

You can create a runner token with the GitHub API or through the repository or organization's Settings. Navigate to Settings > Actions > Runners, click Add Runner, and copy out the --token argument from the config.sh call.

Note that these tokens are only good for 60 minutes, so you must keep the local files created upon registration (after running config.sh) in order to be able to restart your runner. A similar process may be especially useful in Kubernetes, so that Pods can be recreated without manual intervention.

# Create volume to persist authentication and configuration
podman volume create runner
# Perform registration, and copy artifacts to volume
podman run \
    --env RUNNER_TOKEN=$RUNNER_TOKEN \
    --env GITHUB_OWNER=redhat-actions \
    --env GITHUB_REPOSITORY=openshift-actions-runner \
    --env RUNNER_LABELS="local,podman" \
    --rm -v runner:/persistence \
    --entrypoint='' \
    quay.io/redhat-github-actions/runner:latest \
    bash -c "./register.sh && cp -rT . /persistence"
# Run container with volume mounted over runner home directory
podman run \
    --rm -v runner:/home/runner \
    quay.io/redhat-github-actions/runner:latest

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/

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.