OpenShift GitHub Actions Runner Chart

This repository contains a Helm chart for deploying one or more self-hosted GitHub Actions Runners into a Kubernetes cluster. By default, the container image used is the OpenShift Actions Runner.

You can deploy runners automatically using the Self Hosted Runner Installer Action.

Prerequisites

You must have access to a Kubernetes cluster. Visit openshift.com/try or sign up for our Developer Sandbox.

You do not need cluster administrator privileges to deploy the runners and run workloads, though some images or tools may require special permissions.

Installing runners

You can install runners into your cluster using the Helm chart in this repository.

1. Runners can be scoped to an organization or a repository. Decide what the scope of your runner will be.
   • User-scoped runners are not supported by GitHub.
2. Create a GitHub Personal Access Token (PAT) which has the repo permission scope.
   • The user who created the token must have administrator permission on the repository/organization the runner will be added to.
   • If the runner will be for an organization, the token must also have the admin:org permission scope.
   • The default secrets.GITHUB_TOKEN does not have permission to manage self-hosted runners. See Permissions for the GITHUB_TOKEN.
3. Clone this repository and cd into it:

git clone git@github.com:redhat-actions/openshift-actions-runner-chart.git \
&& cd openshift-actions-runner-chart

4. Install the helm chart, which creates a deployment and a secret. Leave out githubRepository if you want an organization-scoped runner.
   • Add the --namespace argument to all helm and kubectl/oc commands if you want to use a namespace other than your current context's namespace.

# PAT from step 2.
export GITHUB_PAT=c0ffeeface1234567890
# For an org runner, this is the org.
# For a repo runner, this is the repo owner (org or user).
export GITHUB_OWNER=redhat-actions
# For an org runner, omit this argument.
# For a repo runner, the repo name.
export GITHUB_REPO=openshift-actions-runner-chart
# Helm release name to use.
export RELEASE_NAME=actions-runner

helm install $RELEASE_NAME ./actions-runner/ \
    --set-string githubPat=$GITHUB_PAT \
    --set-string githubOwner=$GITHUB_OWNER \
    --set-string githubRepository=$GITHUB_REPO \
&& echo "---------------------------------------" \
&& helm get manifest $RELEASE_NAME | kubectl get -f -

5. You can re-run step 4 if you want to add runners with different images, labels, etc. You can leave out the githubPat on subsequent runs, since the secret will be left out if it exists already.

For other configuration options such as resource limits and replica counts, see values.yaml.

The runners should show up under Settings > Actions > Self-hosted runners shortly afterward.

Using your own runner image

See the OpenShift Actions Runner README.

Managing PATs

See the wiki for a note on managing mulitple PATs, if you want to add a new PAT or replace an existing one.

Troubleshooting

The runner containers will crash with an authorization/authentication error (HTTP 401 or 403) if the GitHub PAT they are given is not valid, or does not have the required permission scope. Make sure the githubPat input value contains a token that has the required permission scopes, as outlined in Step 2.

The runner containers will crash with an HTTP 404 if the org, user, or repository name is misspelled, or not visible with the token's permissions.

General guidelines for troubleshooting

You can view the resources created by Helm using helm get manifest $RELEASE_NAME, and then inspect those resources using kubectl get.

The resources are also labeled with app.kubernetes.io/instance={{ .Release.Name }}, so you can view all the resources with:

kubectl get all,secret -l=app.kubernetes.io/instance=$RELEASE_NAME

If the pods are created but stuck in a crash loop, view the logs with kubectl logs <podname> to see the problem.