ForgejoResources

A collection of resources for Forgejo, the self-hosted Git service.

Projects

Project	Description	Best For
ForgejoRunner	Cross-platform runner with auto service installation	macOS, Linux, Windows hosts
ForgejoArcRunner	Kubernetes ARC-style controller	Kubernetes clusters, auto-scaling

ForgejoRunner

Cross-platform Forgejo Actions runner with automatic service installation.

Quick Install

Linux:

curl -fsSL https://forge.blackleafdigital.com/BlackLeafDigital/ForgejoResources/raw/branch/main/ForgejoRunner/scripts/install-linux.sh | bash

macOS:

curl -fsSL https://forge.blackleafdigital.com/BlackLeafDigital/ForgejoResources/raw/branch/main/ForgejoRunner/scripts/install-macos.sh | bash

Windows (PowerShell as Admin):

irm https://forge.blackleafdigital.com/BlackLeafDigital/ForgejoResources/raw/branch/main/ForgejoRunner/scripts/install-windows.ps1 | iex

Register

forgejo-runner register --instance https://your-forgejo.com --token YOUR_TOKEN

This automatically creates directories, registers with Forgejo, installs the service, and starts the runner.

Install System Tools (optional):

sudo curl -fsSL https://forge.blackleafdigital.com/BlackLeafDigital/ForgejoResources/raw/branch/main/ForgejoRunner/scripts/install-system-tools.sh | bash

See ForgejoRunner README for full documentation.

ForgejoArcRunner

Kubernetes controller for Forgejo Actions runners. Uses native runner protocol - no PAT required!

Architecture

┌─────────┐     ┌──────────┐     ┌────────────┐     ┌─────────────┐
│ Forgejo │────▶│ Listener │────▶│ Controller │────▶│ Runner Pods │
└─────────┘     └──────────┘     └────────────┘     └─────────────┘
                  │ Runner Token
                  ▼
              Native Protocol

Features

• Scale-to-zero - No idle resources when no jobs pending
• Pod-per-job - Each workflow job runs in an isolated pod
• Runner token auth - No PAT required
• Multiple container modes - DinD, DooD, or Kubernetes Native

Quick Install

# Install via Helm
helm install forgejo-arc ./ForgejoArcRunner/charts/forgejo-arc-runner/ \
  --set forgejo.url=https://your-forgejo.com \
  --set forgejo.tokenSecretName=runner-token

See ForgejoArcRunner README for full documentation.

Which Should I Use?

Choose ForgejoRunner if:

• Running jobs on existing macOS, Linux, or Windows machines
• Need Docker-based or host-based execution
• Don't have a Kubernetes cluster

Choose ForgejoArcRunner if:

• Have a Kubernetes cluster
• Want automatic pod-per-job isolation
• Need scale-to-zero capability
• Need Windows/ARM/multi-arch support via Kubernetes native mode

Releases

Binaries are available from stable URLs:

Binary	URL
forgejo-runner (Linux amd64)	/releases/download/latest/forgejo-runner-linux-amd64
forgejo-runner (Linux arm64)	/releases/download/latest/forgejo-runner-linux-arm64
forgejo-runner (macOS arm64)	/releases/download/latest/forgejo-runner-darwin-arm64
forgejo-runner (macOS amd64)	/releases/download/latest/forgejo-runner-darwin-amd64
forgejo-runner (Windows)	/releases/download/latest/forgejo-runner-windows-amd64.exe
arc-runner (Linux amd64)	/releases/download/arc-latest/arc-runner-linux-amd64
arc-runner-controller	/releases/download/arc-latest/arc-runner-controller-linux-amd64
arc-runner-listener	/releases/download/arc-latest/arc-runner-listener-linux-amd64

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT