GitHub Actions Poll Mode AutoScaler (GAPMAS)

What

GitHub Actions Poll Mode AutoScaler, or GAPMAS, is a simple tool that helps you run ephemeral GitHub Actions self-hosted runners on your own infrastructure.

Why

• Simplicity

  Minimal infrastructure is required to use the tool, in its simplest form this could be managed from a crontab entry on any Linux machine.

• Poll vs. Push

  The tool reaches out to the GitHub API to look for any queued jobs. The benefit of this approach is that you don't need any service exposed to the internet for this to work.

How

1. Create GitHub Personal Access Token

   • Personal Access Tokens are associated with a GitHub Account.
   • The account itself needs Admin level permissions to the repository you want to manage runners for.
   • The personal access token requires the public_repo scope.

2. Set up Environment variables

   Environment variables

   GH_ORG	The GitHub organization the repository given in GH_REPO resides in.
   GH_REPO	Name of the GitHub repository we operate on.
   GH_USER	Username for authentication to the GitHub API.
   GH_TOKEN	GitHub Personal Access Token.
   OS_KEY_NAME	Name of OpenStack key pair to associate with the instances we create.
   OS_NETWORK_NAME	Name of OpenStack network to attach to the instances we create.
   OS_TAG	Tag to apply to instances. The tool will manage the life cycle of instances and uses this tag to know which instances to operate on.

   • OpenStack client environment
     • The OpenStack provider makes use of the standard OpenStack environment variables for authentication.

3. Set up a job manager to run the tool periodically

   • When a change is proposed to a repository with workflows destined to self-hosted runners, GitHub will queue the job until a runner consumes it.
   • The tool makes use of this behavior to create new runners whenever there are jobs queued.
   • As such choose a cadence for the run which is in line with how long you would expect to wait before your jobs start.

4. Create workflow in repository

   • Workflow jobs with 'self-hosted' as the first label in runs-on will be scheduled for self hosted runners.

   • Labels on the form 'distro-release' will be used as input for what type of image you want the job to run on. Example:

     name: Take out tests
     
     on:
       - push
       - pull_request
     
     jobs:
       hello:
         runs-on: [self-hosted, ubuntu-21.10]
         steps:
           - name: hello
             run: |
               echo "Hello, world!"

   • If an image matching the requested distro/release can not be found the tool will fall back to look for a Ubuntu 20.04 image.