A reverse engineered github actions compatible self-hosted runner using nektos/act to execute your workflow steps. Unlike the official actions/runner, this works on more systems like freebsd.
|Actions Type||Host||JobContainer (only Linux, Windows, macOS or Openbsd)|
|(composite) run steps||
|docker actions||Not available||Docker (*1)|
|service container||Not available||Not available|
|composite actions with uses||v0.1.0||v0.1.0|
|composite actions with if||v0.1.0||v0.1.0|
|composite actions with continue-on-error||v0.1.0||v0.1.0|
Docker Daemon via DOCKER_HOST
(*1) Reachable docker daemon use
DOCKER_HOST to specify a remote host.
NodeJS via PATH
(*2) For best compatibility with existing nodejs actions, please add nodejs in version 12 to your
PATH, newer nodejs versions might lead to workflow failures.
Usage for github releases
Follow the instruction of https://github.com/ChristopherHX/github-act-runner/releases/latest.
Usage for debian repository
Add debian repository
deb http://gagis.hopto.org/repo/chrishx/deb all main
Import repository public key
curl -sS http://gagis.hopto.org/repo/chrishx/pubkey.gpg | sudo tee -a /etc/apt/trusted.gpg.d/chrishx-github-act-runner.asc
Install the runner
sudo apt update sudo apt install github-act-runner
Add new runner
github-act-runner new --url
--name --labels --token
https://github.com/user/repo), organization (e.g.
https://github.com/organization) or enterprise URL
The new runner will be registered and started as background service.
For more info about managing runners.
Usage from source
You need at least go 1.16 to use this runner from source. Some targets fail to build with go 1.17.
git clone https://github.com/ChristopherHX/github-act-runner.git --recursive
git pull git submodule update
go run . configure --url
--name -l label1,label2 --token
https://github.com/ChristopherHX/github-act-runner for this repo
|You find the token in|
|Enterprise||In action runner settings of your enterprise|
label1,label2 with a custom list of runner labels.
go run . run
- actions/cache is incompatible and won't be able to save your cache
- Using https://github.com/actions/toolkit/tree/main/packages/cache directly should allow you to save your cache
- You won't be able to run steps after a failure without using
- Most issues of https://github.com/nektos/act/issues applies to this runner as well
How does it work?
This runner implements the same protocol as the actions/runner in a different way, as such it can be used as a self-hosted runner exactly like the official one. To get this working, I initially built an actions service replacement ChristopherHX/runner.server for the official actions/runner. My own actions service allowed me to implement the base protocol for this runner and debug how the protocol is serializeing and parsing json messages, while still being incompatible with github. After testing against github, the first thing happend was loosing the ability to run any github action workflows on my test repository. My invalid attempts to register a custom runner caused unrecoverable Internal Server Errors on githubs side, I decided to delete this test repository. After some work everything worked and finally it is safe to register this runner against github. To execute steps this runner translates the github actions job request to be compatible with a modified version of nektos/act ( ChristopherHX/act ), which adds a local task runner without the need for docker and increased platform support, also the log output of act gets redirected to github for live logs and storing log files.
Does this runner work without github?
Yes, you can use this runner together with ChristopherHX/runner.server locally on your PC without depending on compatibility with github. Also CI tests for this runner are using ChristopherHX/runner.server, this avoids requiring a PAT for github to run tests and enshures that you are always able to run it locally without github.