May 25, 2021
Édouard Bonlieu
@edouardb_
GitHub Actions allows you to automate your software development workflow lifecycle right in your GitHub repository. The workflows you deployed let you compose a multitude of jobs including CI/CD.
A GitHub Actions workflow is made of a YAML file containing all the configuration and commands to execute on specific events. The workflow execution is made on runners. A runner is the application that runs a job from a GitHub Actions workflow. While GitHub natively provides managed runners, it can be interesting to deploy your own in various cases:
In this guide, we will showcase how to deploy GitHub Actions self-hosted runners on Koyeb and run a basic "Hello World!" GitHub Actions workflow.
To successfully follow and complete this guide you need:
To deploy a self-hosted GitHub Actions runner on Koyeb you need to follow these steps:
The first step is to create a Dockerfile to install GitHub Action runner. We will then build the Docker image and push it to the GitHub container registry. As Koyeb allows you to horizontally scale the number of services, you will be able to deploy as many as you need GitHub runners on Koyeb.
To get started, created a new folder we will create the Dockerfile:
mkdir gh-self-hosted-runner cd gh-self-hosted-runner
In the directory we created, create a Dockerfile
file and paste the content below:
FROM ubuntu:latest ENV RUNNER_VERSION=2.278.0 RUN apt-get update \ && apt-get install -y --no-install-recommends \ ca-certificates \ curl \ libicu-dev \ netcat WORKDIR /gh-runner RUN curl -o actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz -L \ https://github.com/actions/runner/releases/download/v2.278.0/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz RUN tar xzf actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz COPY entrypoint.sh . RUN adduser --no-create-home ghrunner -uid 1001 RUN chown -R ghrunner:ghrunner /gh-runner USER ghrunner EXPOSE 3000 ENTRYPOINT ["/gh-runner/entrypoint.sh"]
You may notice we are installing netcat in the Dockerfile. We realize this operation as the Koyeb platform performs TCP health checks on services you deployed to ensure they are up and running. We use netcat to expose the port 3000 in our GitHub Actions runner application so Koyeb can ensure it is up and running properly.
In the same directory, create an entrypoint.sh
file. This file contains the script our container will execute at boot time:
#!/bin/bash if [ -z ${GH_RUNNER_TOKEN+x} ]; then echo "GH_RUNNER_TOKEN environment variable is not set" exit 1 fi if [ -z ${GH_REPOSITORY+x} ]; then echo "GH_REPOSITORY environment variable is not set." exit 1 fi nohup nc -lk 3000 & /gh-runner/config.sh --url https://github.com/$GH_REPOSITORY --token $GH_RUNNER_TOKEN /gh-runner/run.sh
Build the Docker image by executing the following command:
docker build . -t ghcr.io/<YOUR_GITHUB_USERNAME>/gh-self-hosted-runner
Take care to replace <YOUR_GITHUB_USERNAME>
with your GitHub username
With our Docker image is built, we can now upload it to the GitHub container registry. In your terminal run the command below to push the image.
docker push ghcr.io/<YOUR_GITHUB_USERNAME>/gh-self-hosted-runner
Within a few minutes, you will see your Docker image available on the GitHub container registry: https://github.com/<YOUR_GITHUB_USERNAME>?tab=packages
.
On GitHub, go to the repository you want to use the self-hosted GitHub Actions runner and click the Settings tab. On the left-side menu, click Actions and select runners in the submenu.
You land on the runners settings page. Click the Add runner button to add a new self-hosted runner, the runner configuration page appears.
In the Configure section, copy the token, i.e. here: AATHLD2AEXMPRBIPVTZVHMTAVTEOR
, and save it a safe place. You will need it in the next section when deploying the GitHub Actions runner on Koyeb.
./config.sh --url https://github.com/<YOUR_GITHUB_USERNAME>/runner-test --token AATHLD2AEXMPRBIPVTZVHMTAVTEOR
To deploy the self-hosted GitHub runner on Koyeb, go to the Koyeb Control Panel and click the Create App button.
In the form, fill the Docker image
field with the name of the image we previously created which should look like ghcr.io/<YOUR_GITHUB_USERNAME>/gh-self-hosted-runner
.
Check the box Use a private registry
and, in the select field, click Create Registry Secret.
A modal opens asking for:
gh-registry-secret
In the Ports section, change the export port from 80
to 3000
and from protocol HTTP
to TCP
. This setting is required to let Koyeb performs health checks and ensure your service is up and running properly.
In the Environment variables section create two environment variables:
org-name/repo-name
Give your App a name, i.e gh-self-hosted-runner
, and click Create App
You can add more regions to deploy your applications, and define the horizontal scaling according to your needs.
Yours GitHub Actions self-hosted runner app is now deployed and running. In the next section, we will deploy a Hello World! GitHub Actions workflow executing on our self-hosted runner.
If you do not have any GitHub Actions workflow, in your git repository create a new folder to store our GitHub Actions workflow:
mkdir -p github/workflows cd github/workflows
Create a new file to store our example workflow called main.yaml
and paste the content below:
name: CI on: [push] jobs: build: runs-on: self-hosted steps: - run: echo "Hello from Koyeb runner!"
The workflow above execute on the runner hosted on Koyeb and display "Hello from Koyeb runner!" each time a push occurs on your repository.
To test it, commit and push changes to your repository, in the Actions tabs of your repository on GitHub, you will see the result of the workflow executed by your GitHub runner running on Koyeb.
In your workflow YAML file, edit the runs-on
section of your workflow and set its value to self-hosted
to run a self-hosted GitHub runner:
name: CI on: [push] jobs: build: runs-on: self-hosted ...
In this guide, we demonstrated the benefit of using GitHub actions self-hosted runners and how to deploy them on Koyeb. Questions or suggestions to improve this guide? Join us on the community platform to chat!
Koyeb is a developer-friendly serverless platform to deploy any apps globally.
Start for freeDeploy 2 services for free and enjoy our predictable pricing as you grow
Get up and running in 5 minutes