Building a Lightweight Source Code Management and CI/CD System for Small Teams using Forgejo and Forgejo Runner on ARM VPS

Introduction: The Self-Hosting Dilemma for Small Teams

In the modern software development lifecycle, robust Source Code Management (SCM) and continuous integration/continuous deployment (CI/CD) pipelines are non-negotiable. For years, platforms like GitHub and GitLab have been the default choices. However, as teams scale or project boundaries shift, relying entirely on third-party cloud SaaS models can introduce unexpected costs, data privacy concerns, and rigid vendor lock-in.

For small teams or independent startups, traditional self-hosted alternatives like GitLab CE present an entirely different roadblock: resource consumption. Running a full GitLab instance smoothly often demands multiple gigabytes of RAM and substantial CPU cycles, making affordable, low-spec virtual private servers (VPS) completely non-viable. This is where the combination of Forgejo and Forgejo Runner on an ARM-based VPS emerges as a game-changing solution.

Why Forgejo and ARM VPS are a Perfect Match

Forgejo is an open-source, community-driven fork of Gitea, created to ensure a truly free and community-led git hosting platform. It retains the signature traits that made Gitea famous: it is incredibly lightweight, written in Go, and capable of running on minimal hardware while offering a rich, GitHub-like user interface.

When paired with modern ARM-based cloud infrastructure—such as Oracle Cloud’s Always Free Ampere compute or Ampere-based instances from Hetzner and AWS—the cost-to-performance ratio becomes unmatched. ARM architecture delivers exceptional multi-core performance with significantly lower power consumption and cost compared to traditional x86 counterparts. Running Forgejo on ARM allows you to operate a complete SCM and CI/CD ecosystem for next to nothing, often utilizing less than 500MB of RAM for the core platform.

Prerequisites and Architecture Overview

Before diving into the deployment, let's outline the core components of our architecture:

Host Machine: An ARM64 VPS running a modern Linux distribution (e.g., Ubuntu 22.04 LTS or 24.04 LTS).
Container Runtime: Docker and Docker Compose for isolated, easily manageable service deployment.
Reverse Proxy: Nginx or Caddy to handle SSL/TLS termination and secure HTTP routing.
Database: SQLite (sufficient for small teams) or a lightweight PostgreSQL container.

Note: Forgejo supports SQLite natively, which drastically reduces the memory footprint. For teams under 10 developers, SQLite is highly performant and dramatically simplifies backup routines.

Step 1: Setting Up Forgejo via Docker Compose

To keep the system modular and maintainable, we will use Docker Compose. Create a dedicated directory on your ARM VPS and define the stack configuration.

First, prepare the directory structure:

mkdir -p forgejo/data forgejo/runner

Next, create a docker-compose.yml file in the forgejo directory. This file will orchestrate both our Forgejo instance and the database (if choosing PostgreSQL, though we will focus on the single-container SQLite setup here for maximum efficiency):The configuration specifies the official multi-architecture Docker image for Forgejo, which seamlessly supports linux/arm64. It binds the container's web (3000) and SSH (22) ports to the host, ensuring your team can interact with repositories securely via standard Git workflows.

Step 2: Configuring Forgejo Actions and Registering the Runner

One of Forgejo's most compelling features is Forgejo Actions, a built-in CI/CD engine that is compatible with GitHub Actions workflows. To execute these workflows, we need to deploy a separate daemon: the Forgejo Runner.

To initialize the runner, you must first enable Actions within your Forgejo configuration. Navigate to your instance's Site Administration panel under the Actions tab to retrieve your Registration Token.

Once you have the token, add the Forgejo Runner service to your existing docker-compose.yml or spin it up on a separate instance if you wish to isolate compilation workloads from your primary repository server. The runner utilizes a configuration file where you define its execution labels—mapping tasks to specified container environments (e.g., ubuntu-latest mapped to an ARM64 node image).

After starting the runner container, execute the registration command inside the container using your unique token. Once registered, the runner will appear in the Forgejo admin portal, idling and ready to pick up automated tasks.

Step 3: Optimizing for the ARM Architecture

While Forgejo runs efficiently out of the box, building CI/CD pipelines on ARM requires a minor shift in mindset regarding container images. When writing your workflow YAML files, always ensure that the Docker actions or build steps you use support arm64.

Use Multi-Arch Base Images: Ensure your application Dockerfiles utilize base layers like node:alpine or python:slim which inherently provide ARM64 variants.
Leverage Native Compilation: Running tests and builds directly on native ARM architecture avoids the massive emulation overhead of QEMU, making your CI/CD pipelines exceptionally fast.

Step 4: Securing the Installation

A business-grade deployment requires strict security practices. Ensure your system adheres to the following guidelines:

Enforce HTTPS: Deploy a reverse proxy like Caddy or Nginx with Let's Encrypt certificates to encrypt all web traffic and Git operations over HTTPS.
Disable Public Registration: Modify the app.ini configuration file to set DISABLE_REGISTRATION = true once your team members have created their accounts. This prevents unauthorized users from exploiting your resources.
Restrict SSH Access: Use custom ports or strictly enforced SSH key authentication for repository synchronization.

Conclusion: Enterprise-Grade Control on a Bootstrap Budget

By combining Forgejo, Forgejo Runner, and the cost-effective prowess of ARM architecture, small teams no longer have to compromise between financial constraints and powerful automation. You gain complete ownership of your data, zero third-party platform dependencies, and a fully automated CI/CD environment that runs seamlessly within a fraction of the hardware footprint required by alternative enterprise tools.

Investing a few hours into setting up this self-hosted stack establishes a reliable foundation that can scale with your organization's needs for years to come.