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

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.

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.

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.
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.