A script to deploy an official Gitea Actions Runner in an unprivileged Proxmox VE LXC container with Docker CE pre-installed and configured, styled and structured following Community Scripts (Proxmox VE Helper-Scripts).

   _______ __                   ____                               
  / ____(_) /____  ____ _      / __ \__  ______  ____  ___  _____  
 / / __/ / __/ _ \/ __ `/_____/ /_/ / / / / __ \/ __ \/ _ \/ ___/  
/ /_/ / / /_/  __/ /_/ /_____/ _, _/ /_/ / / / / / / /  __/ /      
\____/_/\__/\___/\__,_/     /_/ |_|\__,_/_/ /_/_/ /_/\___/_/

⚡ Quick Start

Run the following command directly in your Proxmox VE Shell:

bash -c "$(curl -fsSL https://git.mattway.com.au/matt/gitea-runner-script/raw/branch/main/ct/gitea-runner.sh)"

(Optional: You can also clone and run locally on the Proxmox host)

git clone https://git.mattway.com.au/matt/gitea-runner-script.git
./gitea-runner-script/ct/gitea-runner.sh

⚙️ Container Default Specifications

Setting	Default Value	Notes
OS	Debian 12 / 13	Alpine is also selectable during setup
CPU	2 vCPU	Suitable for concurrent CI tasks and compilation
RAM	2048 MB	Sufficient for Docker engine and CI workloads
Disk	15 GB	Provides headroom for caching Docker layers
Type	Unprivileged (`1`)	Enhanced container isolation
Features	`nesting=1`, `keyctl=1`	Required for running Docker inside an unprivileged LXC

🔑 Registering with your Gitea Instance

1. Obtain a Registration Token from Gitea

You can register the runner at the instance level, organization level, or repository level:

Instance-wide: Site Administration → Actions → Runners → Create new Runner
Organization-level: Organization Settings → Actions → Runners → Create new Runner
Repository-level: Repository Settings → Actions → Runners → Create new Runner

Copy the generated Registration Token.

2. Connect the Runner

You can register the runner interactively during installation, or anytime afterwards:

Option A: From Proxmox VE Host Shell

pct exec <CTID> -- gitea-runner-register

Option B: From Inside Container Console

gitea-runner-register

Option C: Non-interactive / Headless Registration

pct exec <CTID> -- gitea-runner-register \
  --instance "https://git.mattway.com.au" \
  --token "<YOUR_REGISTRATION_TOKEN>" \
  --name "pve-runner-01" \
  --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04,ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"

Once registered, the helper starts and enables the gitea-runner.service systemd daemon. The runner will immediately show as Idle (green) in your Gitea web interface!

🛠️ Configuration & Service Management

Configuration file: /etc/gitea-runner/config.yaml (symlinked from /etc/act_runner/config.yaml)
State file: /etc/gitea-runner/.runner
Systemd Service: gitea-runner.service (alias act_runner.service)

Common Management Commands (Inside Container)

Check service status:
```
systemctl status gitea-runner
```
View live logs:
```
journalctl -u gitea-runner -f
```
Restart runner daemon:
```
systemctl restart gitea-runner
```
Verify Docker:
```
docker info
```

🔄 Updating the Runner

Just like other containers created with Community Scripts, you can update this container at any time by simply running the built-in update command:

Option A: From inside the container console

update

Option B: From the Proxmox VE host shell

pct exec <CTID> -- update

Option C: Via curl one-liner

bash -c "$(curl -fsSL https://git.mattway.com.au/matt/gitea-runner-script/raw/branch/main/ct/gitea-runner.sh)"

When executed, the update process automatically:

Runs safe APT OS updates (apt-get update && apt-get upgrade -y).
Checks for Docker engine updates.
Checks for the latest release on the official Gitea repository.
Stops the service, safely updates the binary, and restarts the daemon if a new version is detected.

📁 Repository Structure

Built following the official Community Scripts architecture:

├── ct/
│   ├── gitea-runner.sh          # Proxmox host creation and update script
│   └── headers/
│       └── gitea-runner         # ASCII art banner
├── install/
│   └── gitea-runner-install.sh  # In-container provisioning script
├── gitea-runner.sh              # Root launcher entrypoint
├── LICENSE                      # MIT License
└── README.md                    # Documentation

📄 License

This project is licensed under the MIT License. Built with the foundation and conventions established by community-scripts ORG.