Files

CI / build-and-test (push) Successful in 17s

Details

docs: add HOWTOSTART.md guide for setting up runners

Comprehensive guide covering:
- Prerequisites and quick start
- Registration process
- Labels configuration
- Running as a systemd service
- Docker support
- Capabilities detection
- Troubleshooting tips

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-11 18:18:39 +00:00

3.0 KiB

Raw Permalink Blame History

How to Start a GitCaddy Runner

This guide explains how to set up and start a GitCaddy Actions runner (act_runner) to execute your CI/CD workflows.

Prerequisites

A Linux, macOS, or Windows machine
Network access to your GitCaddy/Gitea instance
(Optional) Docker installed for container-based workflows

Quick Start

1. Download the Runner

Download the latest release from the releases page or build from source:

git clone https://git.marketally.com/gitcaddy/act_runner.git
cd act_runner
make build

2. Register the Runner

Get a registration token from your GitCaddy instance:

Global runners: Admin Area → Actions → Runners → Create Runner
Organization runners: Organization Settings → Actions → Runners
Repository runners: Repository Settings → Actions → Runners

Then register:

./act_runner register --no-interactive \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name my-runner \
  --labels linux,ubuntu-latest

3. Start the Runner

./act_runner daemon

Configuration Options

Runner Labels

Labels determine which jobs the runner can execute. Configure labels during registration or edit them in the admin UI.

Common labels:

linux, linux-latest - Linux runners
windows, windows-latest - Windows runners
macos, macos-latest - macOS runners
ubuntu, ubuntu-latest - Ubuntu-specific
self-hosted - Self-hosted runners

Running as a Service

Linux (systemd)

sudo cat > /etc/systemd/system/act_runner.service << 'SERVICE'
[Unit]
Description=GitCaddy Actions Runner
After=network.target

[Service]
Type=simple
User=runner
WorkingDirectory=/opt/act_runner
ExecStart=/opt/act_runner/act_runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl enable act_runner
sudo systemctl start act_runner

Docker Support

For workflows that use container actions, ensure Docker is installed and the runner user has access:

sudo usermod -aG docker $USER

Capabilities Detection

The runner automatically detects and reports:

Operating system and architecture
Available shells (bash, sh, powershell)
Installed tools (node, python, go, etc.)
Docker availability
Disk space and network bandwidth

These capabilities help admins understand what each runner can handle.

Troubleshooting

Runner not connecting

Check network connectivity to your GitCaddy instance
Verify the registration token is valid
Check firewall rules allow outbound HTTPS

Jobs not running

Verify runner labels match the job's runs-on requirement
Check runner is online in the admin panel
Review runner logs: journalctl -u act_runner -f

3.0 KiB Raw Permalink Blame History