fef300dd5b
All checks were successful
CI / build-and-test (push) Successful in 17s
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>
122 lines
3.0 KiB
Markdown
122 lines
3.0 KiB
Markdown
# 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](https://git.marketally.com/gitcaddy/act_runner/releases) or build from source:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Check network connectivity to your GitCaddy instance
|
|
2. Verify the registration token is valid
|
|
3. Check firewall rules allow outbound HTTPS
|
|
|
|
### Jobs not running
|
|
|
|
1. Verify runner labels match the job's `runs-on` requirement
|
|
2. Check runner is online in the admin panel
|
|
3. Review runner logs: `journalctl -u act_runner -f`
|
|
|
|
## More Information
|
|
|
|
- [act_runner Repository](https://git.marketally.com/gitcaddy/act_runner)
|
|
- [GitCaddy Documentation](https://git.marketally.com/gitcaddy/gitea)
|