
## 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](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on the platform.

## Requirements

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

- A [Koyeb account](https://app.koyeb.com/auth/signup) to deploy and run the GitHub Actions runner.
- A [GitHub account](https://github.com/) 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](#clone-the-koyeb-github-runner-demo-application)
2. [Create a new GitHub personal access token](#create-a-new-git-hub-personal-access-token)
3. [Deploy the GitHub runner on Koyeb](#deploy-the-git-hub-runner-on-koyeb)
4. [Test the runner](#test-the-runner)

## Clone the Koyeb GitHub runner demo application

To get started, visit the [Koyeb GitHub runner demo application repository](https://github.com/koyeb/koyeb-github-runner-demo) 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:

```yaml
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**](https://github.com/settings/profile). From there, go to [**Developer settings**](https://github.com/settings/apps) at the bottom of the left hand navigation menu and select [**Fine-grained tokens**](https://github.com/settings/tokens?type=beta) under the **Personal access tokens** section. Click [**Generate new token**](https://github.com/settings/personal-access-tokens/new) 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](https://github.com/koyeb/koyeb-github-runner#repository-or-organization-runner) 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](https://hub.docker.com/r/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:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=github-runner&service_type=worker&privileged=true&type=docker&image=docker.io/koyeb/github-runner&env[REPO_URL]=CHANGE_ME&env[GITHUB_TOKEN]=CHANGE_ME&env[RUNNER_LABELS]=koyeb-runner&ports=8000;http;/)

If you'd like to deploy manually, in **Overview** tab of the [Koyeb control panel](https://app.koyeb.com/), 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:

```bash
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:

![Koyeb runner test](/static/images/tutorials/koyeb-github-runner/runner-output.png)

# 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](https://github.com/koyeb/koyeb-github-runner) and [Docker Hub page](https://hub.docker.com/r/koyeb/github-runner).

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](/tutorials/dynamically-start-github-action-runners-on-koyeb).


Learn how to deploy and run GitHub Actions self-hosted runners on Koyeb serverless platform.

CICD

Deploying GitHub Actions Self-Hosted runners on Koyeb