Skip to main content

Self hosted github actions runners for HMPPS

Introduction

This document is an overview of using self-hosted GitHub organization runners that can be used for HMPPS projects.

Benefits and limitations

Organization-based self-hosted runners can be used:

  • To save costs when running GitHub Actions across multiple repositories within an organization.
  • To centralize runner management, reducing idle time by sharing runners across repositories.
  • To allow actions and their scripts to gain access to internal endpoints within the CloudPlatform cluster.

Examples of use cases:

  • End to end testing of applications
  • Health checks and scans
  • Any job that needs access to an endpoint only accessible within Cloudplatform.

However, there are limitations:

  • Organization-based runners require careful management of permissions to ensure they are not misused by unauthorized repositories, to this end you need to request access, see below.
  • No root user access.: since they run in a container within CloudPlatform’s kubernetes cluster, for security reaason there is no access to the root user.
  • No docker commands - running docker requires root access.

How to use self-hosted runners in your project.

  • First you need to request for your projects github repository be given permission to use the hmpps org based runners in #ask-prisons-digital-sre slack channel.
  • Once permission is granted you should be able to see the runners when you navigate to actions section of your repository, see further docs here:.
  • Next update your github actions workflow file to include the runs-on parameter:
runs-on: [self-hosted, Linux, X64, hmpps-github-actions-runner]

Note: we currently only build and run Linux, X64 OS and architecture of the runner.

Further documentation here

Example with context:

on: workflow_dispatch

jobs:
  test:
    runs-on: [self-hosted, Linux, X64, hmpps-github-actions-runner]
    steps:
    - run: echo Hello world!

Request additional software/tools to be included

Since self-hosted runner are not allowed root access - if you try to install certain tools or software it may fail, please raise a request for this in #ask-prisons-digital-sre and we can discuss your requirements, and perhaps add it to the base image.