
## 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.

Deploying GitHub Actions Self-Hosted runners on Koyeb


## Introduction

GitHub Actions are a great way to automate parts of your development and release workflows by running jobs in response to repository events. While native runners are available to execute these jobs on GitHub, often self-hosting your runners can provide a better price-performance ratio.

In our [guide on running GitHub runners on Koyeb](/tutorials/deploying-github-actions-self-hosted-runners-on-koyeb), we demonstrated how to configure Koyeb GitHub runners to execute GitHub Actions for an example application. This configuration lets us choose the appropriate performance profile for our tasks while saving money compared to the higher-tier native GitHub runners. One problem, however is that you don't necessarily need the runners operating at all times. When no jobs are being run, this needlessly increases costs without providing any value.

In this guide, we'll show you how to improve the Koyeb GitHub runner configuration by taking advantage of a companion project, [`koyeb-github-runner-scheduler`](https://github.com/koyeb/koyeb-github-runner-scheduler). Instead of deploying a continuously-running, high-performance GitHub runner on Koyeb directly, you can deploy a smaller scheduler app that dynamically spins up GitHub runners as necessary to complete jobs. The Koyeb Scheduler can be used to dispatch jobs for either an entire organization or for a specific repository. We'll be configuring our Scheduler to run for a specific repository in this demonstration.

## How the scheduler works

The scheduler is a small application that you can deploy on Koyeb to manage GitHub Actions job requests. It listens for jobs from GitHub and dispatches them to an appropriate runner on Koyeb. If a runner is not available, the scheduler provisions a new one and hands the job over once it is running. It automatically spins down the GitHub runners that have been idle for a configurable period of time.

This system allows you to run a small, always-on application and dynamically provision high-performance resources to execute your jobs when needed. You can configure the scheduler to receive requests from an entire organization or a single repository.

The basic order of operations that occurs when a GitHub Action, like a unit test, is triggered is as follows:

1. Your GitHub repository sends a webhook to the Koyeb Scheduler.
2. The Koyeb Scheduler checks if an appropriate runner is available to run the job. If one is not found, it initiates a new runner instance on Koyeb, tailored to your pre-defined size and geographic location requirements.
3. The Koyeb Scheduler dispatches the job to the matching GitHub runner.

After a pre-configured timeout, the Koyeb Scheduler shuts down the runner if no new jobs are initiated. This timeout is adjustable, offering you further control over cost and performance.

## Requirements

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

- A [Koyeb account](https://app.koyeb.com/auth/signup) to deploy and run the Koyeb Scheduler.
- A [GitHub account](https://github.com/) to store your repositories and configure the GitHub Actions behavior.

## Steps

In this guide, we'll deploy the Koyeb Scheduler on Koyeb and configure GitHub to pass GitHub Actions jobs to it through the following steps:

1. [Clone the Koyeb GitHub runner scheduler demo application](#clone-the-koyeb-git-hub-runner-scheduler-demo-application)
2. [Create a GitHub personal access token](#create-a-git-hub-personal-access-token)
3. [Create a Koyeb personal access token](#create-a-koyeb-personal-access-token)
4. [Deploy the Koyeb GitHub Scheduler on Koyeb](#deploy-the-koyeb-git-hub-scheduler-on-koyeb)
5. [Configure a webhook for the GitHub repository](#configure-a-webhook-for-the-git-hub-repository)
6. [Test the Scheduler](#test-the-scheduler)

## Clone the Koyeb GitHub runner scheduler demo application

To get started, visit the [Koyeb GitHub runner scheduler demo application repository](https://github.com/koyeb/koyeb-github-runner-scheduler-demo) and clone it to your account.

The repository contains the same code from the [Koyeb GitHub runner demo application](https://github.com/koyeb/koyeb-github-runner-demo), but with a different GitHub Actions definition:

```yaml
name: Run unittests

on:
  push:
    branches:
      - '*'

jobs:
  run-tests-in-frankfurt:
    runs-on: koyeb-fra-small
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Run tests
        run: |
          echo "Hello from a Small Koyeb Instance in Frankfurt!"
          python -m unittest
```

Rather than targeting a runner based on the `koyeb-runner` label, this action uses the format expected by the Scheduler:

```
koyeb-<REGION>-<INSTANCE_TYPE>
```

You can find the available values for [regions](/docs/reference/regions#core-regions) and [instance types](/docs/reference/instances#instance-types) in the Koyeb documentation. This allows the Scheduler to spin up different runners of various sizes in different locations depending on what the job requires.

## Create a GitHub personal access token

Before we can deploy the Koyeb Scheduler on Koyeb, we need to generate a new personal access token in GitHub.

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-scheduler` repository](https://github.com/koyeb/koyeb-github-runner-scheduler#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 later. This value cannot be retrieved later, so the token will have to be recreated if you lose it.

## Create a Koyeb personal access token

In order to spin up resources on your Koyeb, the Koyeb Scheduler needs a token that authorizes it to do so.

To get started, in the [Koyeb control panel](https://app.koyeb.com/), click your user icon in the top right corner and click [**Account settings**](https://app.koyeb.com/user/settings). Click the [**Personal Access Tokens**](https://app.koyeb.com/user/settings/api) item in the left-hand menu.

Give your new token a recognizable name and a useful description and then click **Create API Access Token**. Copy the token value and store it in a safe location so that we can use it in the next step. This value cannot be retrieved later, so the token will need to be recreated if you lose it.

## Deploy the Koyeb GitHub Scheduler on Koyeb

Now that we have the GitHub and Koyeb tokens, we can deploy the [Koyeb GitHub Scheduler](https://hub.docker.com/r/koyeb/github-runner-scheduler) to our account.

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

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=github-runner-scheduler&type=docker&image=docker.io/koyeb/github-runner-scheduler&env[GITHUB_TOKEN]=CHANGE_ME&env[KOYEB_TOKEN]=CHANGE_ME&env[API_SECRET]=CHANGE_ME&env[MODE]=repository&env[DISABLE_DOCKER_DAEMON]=true&ports=8000;http;/)

If you'd like to deploy manually, on the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com/), click **Create Web Service** to get started:

1. Select **Docker** as the deployment method.
2. Enter `github.io/koyeb/github-runner-scheduler` as the **Docker image**.
3. In the **Environment variables** section, create the following variables:
   - `GITHUB_TOKEN`: The personal access token you generated on GitHub.
   - `KOYEB_TOKEN`: The personal access token you generated on Koyeb.
   - `API_SECRET`: A random secret used to authenticate requests from GitHub webhooks. You will need to provide the same value when configuring the webhook on GitHub afterwards. A good way to generate this secret is by using the output of this command: `openssl rand -base64 30`.
   - `MODE`: Set this to `repository` since we're configuring the Scheduler for a single repository (if we were [configuring for an organization](https://github.com/koyeb/koyeb-github-runner-scheduler#repository-or-organization-runner), this would instead be set to `organization`).
     Additionally, you may also want to set the following optional variables depending on your needs:
   - `DISABLE_DOCKER_DAEMON`: Set this to `true` if you do not need to start a Docker daemon to run your jobs. Disabling this will reduce both the startup time and memory usage for your runners. If you're using the Python application from the previous guide, you can safely set this to `true`.
   - `RUNNERS_TTL`: You can optionally set this to the number of minutes after the most recent job that you want to wait before spinning down the GitHub runners. The default behavior is to wait 120 minutes (2 hours).
4. When you are ready, click **Deploy** to start up the Koyeb GitHub Scheduler on your account.

On the Service page, copy the **Public URL** for your Scheduler. You'll need it when configuring the webhook in the next step.

## Configure a webhook for the GitHub repository

Now that the Scheduler is up and running, you can finish the integration by configuring a webhook for the repository.

On your GitHub repository page, click the **Settings** tab and select **Webhooks**. Click **Add webhook** to begin the configuration.

Paste the public URL you copied from your Koyeb Scheduler into the **Payload URL** field. For the **Content type**, select `application/json`. In the **Secret** field, paste the same secret you used as the value for the `API_SECRET` environment variable when deploying the Scheduler.

In answer to the question **Which events would you like to trigger this webhook?**, choose **Let me select individual events.** In the list that follows:

- **De-select** the **Pushes** item
- **Select** the **Workflow jobs** item

Click **Add webhook** when you are finished.

## Test the Scheduler

Once you push your new changes to GitHub, the workflows should begin to execute using the new Scheduler system.

If you visit the runtime logs of the Koyeb GitHub Scheduler app in the Koyeb control panel, there should be messages indicating that a new job has been received from GitHub. They'll look for GitHub runners with the appropriate label and, finding none, will provision the new instance:

![Koyeb Scheduler event logs](/static/images/tutorials/koyeb-github-scheduler/koyeb-scheduler-logs.png)

If you go back to the main [Koyeb Apps list](https://app.koyeb.com/), a new GitHub runner Service should be in the process of deploying in Frankfurt:

![Koyeb new GitHub runner services](/static/images/tutorials/koyeb-github-scheduler/koyeb-new-runner-services.png)

Next, visit the **Actions** tab in your GitHub repository. You should see the test run history. If you click through the jobs, you'll a new job defined by your workflow:

![GitHub Actions test run results](/static/images/tutorials/koyeb-github-scheduler/github-actions-results.png)

The GitHub Actions were successfully executed by runners that the Scheduler dynamically provisioned. After the idle timeout is reached, the Scheduler will delete the runner, saving you money when it is not being used.

## Conclusion

In this guide, we improved a self-hosted GitHub runners set up by replacing our always-on GitHub runners with Koyeb Scheduler, a small application that can dynamically provision runners as needed. We configured the GitHub repository to send webhook messages to the Scheduler when GitHub Actions jobs occur and modified the workflow file to use the Scheduler label syntax.

By replacing the GitHub runner with the Scheduler, we are able to more easily control costs by only running instances when required by our GitHub jobs. By adjusting the time-to-live value for runners, we can confidently use higher performance instances without having to worry about paying for unnecessary usage.

To learn more about using the Koyeb Scheduler for your projects, check out the [Koyeb Scheduler repository on GitHub](https://github.com/koyeb/koyeb-github-runner-scheduler) and the [Scheduler image on Docker Hub](https://hub.docker.com/r/koyeb/github-runner-scheduler).


In this tutorial, we'll demonstrate how to configure the Koyeb GitHub Scheduler to dynamically provision GitHub Action runners on Koyeb.

GitHub Actions

Deploying GitHub Actions Self-Hosted runners on Koyeb

Dynamically Start GitHub Action Runners on Koyeb