Self hosted GitHub Actions runner based on UBI (Universal Base Image) 8.
By default, GitHub Actions makes use of runners to execute jobs. Runners can either by managed by the GitHub hosting service of self hosted. The contents of this repository contains a Self Hosted GitHub Actions Runner packaged as a container instance.
Self hosted runners can be scoped at a repository or account/organization level and is configured automatically based on the set of values provied to the container.
The following prerequisites must be met prior to using the content contained within this repository
- Personal Account Token - A GitHub Personal Account Token (PAT) must be available for the runner to connect to GitHub.
OpenShift can be used to build and deploy the self hosted runner. A set of OpenShift templates are available to streamline the generation of the necessary resources.
The following templates are available:
- github-runner-ubi8-build.yaml - Builds the GitHub Runner image
- github-runner-ubi8-deployment.yaml - Deploys the GitHub Runner image
The provided templates which builds and deploys the self hosted running contains a number of parameters to fine tune the necessary configuration for operational use. While the majority of these parameters can be left at their default values, the following variables will most likely need to be defined:
Name | Description | Required |
---|---|---|
GITHUB_PAT |
GitHub Personal Access Token | Yes |
GITHUB_OWNER |
GitHub account or organization | Yes |
GITHUB_REPOSITORY |
GitHub repository | No |
First, create a new project
$ oc new-project github-runner-ubi8
Change into the runner directory:
$ cd github-runner-ubi8
Execute the following command to instantiate the templates using the OpenShift CLI:
Instantiate the build template:
$ oc process -f .openshift/templates/github-runner-ubi8-build.yaml -p | oc apply -f-
Instantiate the deployment template:
$ oc process -f .openshift/templates/github-runner-ubi8-deployment.yaml -p GITHUB_OWNER=<github_owner> -p GITHUB_REPOSITORY=<github_repository> -p GITHUB_PAT=<github_pat> -p | oc apply -f-
Use the following steps to instantiate the templates using the OpenShift web console.
- In your project, click
Add to Project
>Import YAML / JSON
in the top right hand corner - The
Import YAML / JSON
window will appear. Copy the contents of the template and paste it into the window. Alternatively, select theBrowse
button to navigate to the file located on your machine. Once complete, clickCreate
. - An option will appear to
Add a template
. By default, the option wil be selected toProcess this template
. Keep the defaults selected and pressContinue
. - First, the
github-runner-ubi8-build
template will appear. ClickCreate
to instantiate the template. - Repeat steps 1-3 to process the
github-runner-ubi8-deployment
template. Update the desired values of your choosing and insert the required values as described previously. ClickCreate
to instantiate the template.
Once both templates have been instantiated, an image build will begin and once complete, the runner will be deployed.
Once the self hosted runner has been deployed, perform the following steps to confirm the runner is ready to take on jobs:
- Validate container logs
Confirm the runner registration by viewing the logs from the running container
$ oc logs $(oc get pods -l=deploymentconfig=github-runner-ubi8 -o name --no-headers=true)
The following is the expected output
--------------------------------------------------------------------------------
| ____ _ _ _ _ _ _ _ _ |
| / ___(_) |_| | | |_ _| |__ / \ ___| |_(_) ___ _ __ ___ |
| | | _| | __| |_| | | | | '_ \ / _ \ / __| __| |/ _ \| '_ \/ __| |
| | |_| | | |_| _ | |_| | |_) | / ___ \ (__| |_| | (_) | | | \__ \ |
| \____|_|\__|_| |_|\__,_|_.__/ /_/ \_\___|\__|_|\___/|_| |_|___/ |
| |
| Self-hosted runner registration |
| |
--------------------------------------------------------------------------------
# Authentication
√ Connected to GitHub
# Runner Registration
√ Runner successfully added
√ Runner connection is good
# Runner settings
√ Settings Saved.
√ Connected to GitHub
2020-07-27 04:07:48Z: Listening for Jobs
- Confirm the runner has been registered within repository
Browse to a repository that should be served by this runner. Runners are defined within the Actions section of the repository settings
- Click Settings
- On the left hand navigation pane, select Actions.
Locate the runner under the Self-hosted runners section which contains the name of the pod. If no jobs are currently active, the runner will have a state of Idle indicating that it is ready to serve the next job execution.
As part of the configuration of any GitHub actions workflow, the target runner instance must be specified. The runs-on
field allows for the name of the GitHub hosted runner to be defined or a set of labels associated to a registered self hosted runner.
The follow is an example of how to define a hosted runner within a workflow:
...
jobs:
build:
runs-on: [self-hosted, linux]
steps:
- name: Checkout code
uses: actions/checkout@v1
...
The labels associated with the self hosted runner can be specified by defining the template parameter RUNNER_LABELS
.
To learn more about how to use a self hosted runner in a workflow, click here.