senither/github-actions-controller repository overview

⁠GitHub Actions Controller

The GitHub Actions Controller is a Docker controller that provides auto-scaling for GitHub action workflow runners used within an organization.

The project is built using TypeScript and uses Docker⁠ as the underlying container runtime.

When running the controller, it will watch for new actions and will create a new runner for each workflow. The runner will be created using the GitHub Actions Runner⁠, after the workflow has finished, the runner will be deleted to free up resources.

⁠Table of Contents

• Usage⁠
• Setting up Webhook⁠
• Configuration⁠

⁠Usage

The container can be started by running the following command:

docker run -d \
  --name github-actions-controller \
  --restart always \
  -e PORT=8000 \
  -e ORGANIZATION=<your github organization> \
  -e ACCESS_TOKEN=<your github access token> \
  -e CONTAINERS_MAX=10 \
  -e CONTAINERS_TTL=3600 \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  senither/github-actions-controller:latest

Alternatively, you can start the controller using Docker Compose.

version: '3.7'

services:
  controller:
    restart: unless-stopped
    build:
      context: .
      dockerfile: Dockerfile
    image: senither/github-actions-controller
    environment:
      APP_ENV: production
      APP_DEBUG: false
      PORT: 8000
      ORGANIZATION: ${ORGANIZATION}
      ACCESS_TOKEN: ${ACCESS_TOKEN}
      CONTAINERS_MAX: 10
      CONTAINERS_TTL: 2700
    networks:
      - controller
    ports:
      - 8000:8000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

# Networks to be created to facilitate communication between containers
networks:
  controller:
    driver: bridge

The environment variables can now be stored in a .env file next to the docker-compose.yml file, once that's created and setup you can now start the controller by running:

docker compose up -d

⁠Setting up Webhook

After the container is up and running you'll need to register the webhook API route as a webhook in GitHub, to do this you can do the following:

1. Go to your GitHub organization settings
2. Click on Webhooks
3. Create a new webhook that will hit the /webhook route in the container
   1. Ensure the content type is set to application/json
   2. Select the "Let me select individual events" option, and then enable "Workflow jobs"

And that should be it, the container will now be notified by GitHub when new workflows are queued, in-progress, and completed, which it can then use to start and stop the action runners when needed.

⁠Configuration

The controller can take in a few environment variables to modify the behavior of the controller, a list of all the environment variables can be found below.

⁠APP_ENV

The application environment the controller is being started as, if the environment is not set to production the controller will start a dummy container instead of the actions runner to not spam create and delete GitHub runners.

⁠APP_DEBUG

Determines if the debug logging output should be sent to the console or not.

⁠PORT

The port the web API should be running on, this is also used to handle the webhook requests.

⁠ORGANIZATION

The GitHub organization the ACCESS_TOKEN is created for, this is used to tell the controller and the actions runner which organization to register the runners for.

⁠ACCESS_TOKEN

The GitHub access token, the token must be a fine-grained token⁠ with access to the organization with permissions to read and write to the organization's runners and administration, the administration permissions are used to delete offline runners from the organization.

⁠CONTAINERS_MAX

The maximum amount of action runner containers that the controller should be running at a time.

⁠CONTAINERS_TTL

The maximum amount of seconds an action can run before it's counted as having timed out, timed-out actions will be removed from the internal webhook queue.