Introduction

GitHub Actions let you automate parts of your software development workflow within your GitHub repositories. You can compose workflows with many different jobs to accomplish complex tasks as CI/CD pipelines.

GitHub Actions workflows are defined in YAML files within the repository. The files outline the jobs that should be performed and what type of machines should be used to execute each step. The machines that execute GitHub Action jobs are called runners.

Why host your own runners for GitHub Actions?

GitHub provides its own runners to execute jobs on the platform for free. However, there are many cases where it makes more sense to run on other hardware:

• Performance: GitHub's free runners are rather slow. Their paid tier offers better performance, but at a steep price.
• Flexibility: You might need to run your workflow jobs on specific operating systems, hardware, or processor architectures not offered by GitHub.
• Resource access: Your jobs might need to interact with resources that aren't accessible from GitHub, like services running on private networks, for example.
• Control: You might need to dictate exactly where and how your processing occurs, for example, to conform to compliance requirements.

In this tutorial, we'll cover how to use Koyeb to host your GitHub Actions runners for better performance with more competitive pricing. We'll create a basic Python example project with unit tests, and then demonstrate how to configure GitHub and Koyeb to run a self-hosted runner on the platform.

Requirements

To follow along with this guide, you'll need:

• A Koyeb account to deploy and run the GitHub Actions runner.
• A GitHub account to store our repository and create the GitHub Actions configuration.

Steps

In this guide, we'll deploy a self-hosted GitHub Actions runner on Koyeb and configure GitHub to use the runner to deploy and test our Python project through the following steps:

1. Clone the Koyeb GitHub runner demo application
2. Create a new GitHub personal access token
3. Deploy the GitHub runner on Koyeb
4. Test the runner

Clone the Koyeb GitHub runner demo application

To get started, visit the Koyeb GitHub runner demo application repository and clone it to your account.

The repository contains a very simple Python application in app.py along with a single unit test defined in test_app.py.

It also contains a GitHub Actions job defined in .github/workflows/unittests.yml that runs the unit test whenever new changes are detected:

name: Run unittests

on:
  push:
    branches:
      - '*'

jobs:
  run-tests:
    runs-on: koyeb-runner
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Run tests
        run: |
          python -m unittest

This file configures a GitHub Action called Run unittests that executes automatically whenever new changes are pushed to any branch. The job it defines checks out the code and runs the unit test we defined.

The important thing to note is that it is marked to run on koyeb-runner, a label we'll register on Koyeb later.

Create a new GitHub personal access token

In order to access and perform actions on behalf of your account, the runner we'll be deploying needs a GitHub personal access token.

On GitHub, click your user icon in the top right corner and go to Settings. From there, go to Developer settings at the bottom of the left hand navigation menu and select Fine-grained tokens under the Personal access tokens section. Click Generate new token to access the token creation form.

Give the token a name and set the expiration date as you'd like. In the Repository access section, choose Only select repositories and then choose the project repository. In this tutorial, we focus on configuring the token for a single repository, but you can check the koyeb-github-runner repository for instructions on configuring for an entire organization.

In the Permissions section, expand the Repository permissions category. In the drop down menu for the Administration permission, select Read and write.

When you are finished, click Generate token. Copy the token value and store it in a safe location so we can use it in the next step. This value cannot be retrieved later, so the token will have to be recreated if you lose it.

Deploy the GitHub runner on Koyeb

Now, we have everything we need to deploy the Koyeb GitHub runner to execute the GitHub Actions for the repository.

Click the "Deploy to Koyeb" button to configure the deployment. Be sure to alter the REPO_URL and GITHUB_TOKEN environment variables to reflect your own values:

If you'd like to deploy manually, in Overview tab of the Koyeb control panel, click Create Worker Service to get started:

1. Select Docker as the deployment method.
2. Enter docker.io/koyeb/github-runner as the Docker image.
3. In the Deployment section, enable the Privileged setting.
4. In the Instance section, choose Medium or larger.
5. In the Environment variables section, click the Add variable button to create the following variables:
   • REPO_URL: Set to your repository's URL. Should have the form of https://github.com/<YOUR_GITHUB_ORG>/<YOUR_REPO_NAME>.
   • GITHUB_TOKEN: The personal access token you generated on GitHub.
   • RUNNER_LABELS: Set to koyeb-runner. This value must match the runs-on value from your GitHub action file.

When you're finished, click Deploy to start your GitHub runner.

Test the runner

Once the GitHub runner is up and running, visit your repository on GitHub. In the Settings for the repository, select Actions and click Runners. You should see the new runner from Koyeb registered with the koyeb-runner label.

To test that your runner works, create an empty commit on the repository and push it up to GitHub:

git commit --allow-empty -m 'Test runner'
git push origin main

If you visit the Actions tab in your GitHub repository, you should see the test run history. If you click through the jobs, you'll see your unit tests being run by the Koyeb runner:

Conclusion

In this guide, we set up a basic Python app with a unit test to demonstrate how to configure and deploy self-hosted GitHub Actions runners on Koyeb. We launched a Koyeb GitHub runner as a container on the platform and configured it to accept jobs from our repository. We tested the workflow and confirmed that the runner can register with our GitHub repository and run the test suite we set up.

GitHub Actions are a great way of automating routine tasks when you push changes to your repository so that you can run tests, update deployments, build artifacts, and more. Being able to configure and provision your own self-hosted runners gives you more flexibility, control, and performance at a better price than GitHub offers in its own runners.

For additional information about using the Koyeb GitHub runner, check out the GitHub repository and Docker Hub page.

To learn how to dynamically start up Koyeb GitHub runners on demand to help control costs, check out our guide on running dynamic Koyeb GitHub runners.