Overview

Gitea ships with its own built-in CI/CD system called Gitea Actions but it needs a runner to actually execute jobs. This guide covers deploying a dedicated act_runner LXC container on Proxmox and registering it to your Gitea instance, laying the groundwork for automated Hugo builds and deploys.

Hardware / Requirements

  • Gitea already installed and running (see my Private Git Server with Gitea on Proxmox guide if you haven’t set this up yet).
  • Admin access to your Gitea instance to enable Actions and generate a registration token.

🌐 Prerequisite: Gitea Actions is disabled by default and must be enabled in your instance’s configuration before a runner can connect to it.

Procedure

Step 1: Enable Gitea Actions

  1. Open your Gitea configuration (app.ini) on the Gitea container.
  2. Under the [actions] section, set ENABLED = true.
  3. Restart the Gitea service to apply the change.
  4. In the Gitea web UI, go to your repository (or instance-wide) Settings → Actions to confirm it’s active.

Step 2: Create the Runner Container

  1. In Proxmox, click Create CT to spin up a new lightweight LXC container (e.g. gitea-runner).
  2. Allocate 1-2 vCPUs and 1-2GB RAM enough for building a static Hugo site.
  3. Start the container and open its console.

Step 3: Install and Register act_runner

  1. Download the latest act_runner binary inside the container.
  2. Make it executable and move it to a convenient location.
  3. In the Gitea web UI, go to Site Administration → Actions → Runners and click Create new Runner to generate a registration token.
  4. On the container, run the registration command with your Gitea instance URL and the token.
  5. Start act_runner as a systemd service so it stays running and auto-starts on boot.
  6. Confirm the new runner shows as Idle in the Gitea Runners page.