Skip to content

Latest commit

 

History

History
116 lines (83 loc) · 3.63 KB

README.rst

File metadata and controls

116 lines (83 loc) · 3.63 KB
Raw

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.