mirego/ekiden

GitHub Actions self-hosted arm64 macOS runners

Introduction

The goal of this project is to have a pool of GitHub Actions self-hosted runners in addition to the runners provided by GitHub. Those runners are executed inside an ephemeral arm64 macOS machine.

This repo is a collection of documentation, scripts and configuration files that can be used to manage those runners. It uses Tart to orchestrate the virtual machine, Packer to provision these images, Gitea to store the images and Grafana to monitor runners.

Configuration

To configure a new host machine, follow the host configuration guide
To create a new VM, follow the guest configuration guide
To setup the VM registry, follow the registry configuration guide
To setup Grafana to monitor the machines, follow the monitoring configuration guide

How it Works

In order to simplify maintenance and to increase the runner's reliability and the build's repeatability, each runner runs inside an ephemeral virtual machine. This way, whenever a runner picks up a job, the workspace is assured to be in a clean state. Since this is also how the GitHub-hosted runners work, this can simplify interoperability.

A typical run-loop looks like this:

The host machine pulls the most recent VM from the VM registry.
The host machine generates a token from the GitHub API.
The host machine launches a virtual machine (guest) with a cloned virtual disk.
The host machine initiates an SSH connection to the guest.
The host machine launches the "runner" software pre-installed on the VM using the generated token.
The guest machine waits for a job and executes it.
The guest machine de-registers the runner from GitHub.
The host machine shuts down the VM
The host machine deletes the cloned virtual disk
Repeat

flowchart LR
    subgraph local [On-Premise Network]
        subgraph spacer [ ]
            subgraph host [macOS Runner Host]
                subgraph spacer2 [ ]
                    script(Launch Script)-->runner(SSH Client)
                    subgraph guest [macOS VM]
                        runner(GitHub Actions Runner)
                    end
                end
            end
        end

        registry[(VM Registry)]-->script
    end

    subgraph internet [Internet]
        runner<-->github(GitHub Actions)
    end


    style local fill:transparent,stroke:#b38fff,stroke-dasharray:5
    style internet fill:transparent,stroke:#4080ec,stroke-dasharray:5
    style github fill:#4080ec,color:#ffffff
    style spacer fill:transparent,stroke:transparent
    style spacer2 fill:transparent,stroke:transparent

    style guest fill:#cfb9ff,stroke:#a57aff
    style host fill:#ece3ff,stroke:#b38fff
    style registry fill:#b5ee7c,stroke:#8cb960,color:#70934d

License

About Mirego

Mirego is a team of passionate people who believe that work is a place where you can innovate and have fun. We’re a team of talented people who imagine and build beautiful Web and mobile applications. We come together to share ideas and change the world.

We also love open-source software and we try to give back to the community as much as we can.