Skip to main content
Version: v4 (current)

Overview

Projects often encounter a constraint or requirement which makes free-tier hosted CI/CD runners insufficient for their needs. In these cases hosting your own CI/CD runner can be a viable alternative to premium-tier services or subscriptions. Self-hosting may also provide access to resources that are simply not available on many CI/CD services such as GPUs, faster drives, and newer CPU models.

This guide will cover basic methods for hosting CI/CD runners on Bare-Metal, Virtual Machines, or using Cloud Runner. Containerized hosts will not be discussed because of their inherent reliance on insecure practices such as Docker-in-Docker, Privileged Containers and the additional tooling required to mitigate those risks such as Kaniko or Kata Containers.

📚 Prerequisite Knowledge​

Users of this guide should already be familiar with the Linux command-line, Shell scripting, and have a basic grasp of CI/CD concepts. For users who are not familiar with these concepts, we have included some resources for you to start your learning journey below.

📋 Constraints​

There are many ways to self-host CI/CD runners, and which one is best for you will depend on your own situation and constraints. For the purpose of this guide we will make the following assumptions:

  • 💻 User already has their own hardware
  • 💸 Budget for new hardware, software, or services is $0
  • 🛠️ FOSS tools should be prioritized where possible
  • 📜 We define Self-Hosting in this context to refer to a user taking responsibility for the operating-system level configuration and life-cycle-management of a given compute resource (metal, on-prem, cloud VM, VPS etc...)

⚠️ Security Disclaimer​

This guide strives to maintain a balance between convenience and security for the sake of usability. The examples included in this guide are intended for use with on-prem hardware without public IP addresses accessible from external networks. Security is a constantly moving target which requires continuous effort to maintain. Users should conduct their own security review before using the following techniques on production or public systems.

⚡️ Power Costs​

Hosting your own runners also comes with an increase in power consumption. This will vary based on the hardware you use and the prices of energy in your area. Below are some useful resources for discovering the potential energy costs of self-hosting.

💻 System Requirements​

This guide is tested on devices which meet the following requirements:

  • x86 or amd64 processor
  • Ubuntu 22.04 LTS Server or Debian 12 Bookworm
  • Root access to the operating system
  • Network connectivity

📎 Quick Links:​

Host Creation​

"Host Creation" in this context is the process of installing an operating system onto a piece of physical hardware, or the creation and configuration of virtualised compute resources.

Host Provisioning​

"Provisioning" here refers to the process of installing additional resources onto, and the configuration of your host beyond installing the base operating-system. Both manual and declarative workflows are supported.

Runner Application Installation​

Once your host has been provisioned, you will then need to install the appropriate runner application. The guides below will walk you through that process.