IQVForge Runner

Türkçe · Setup guide · Kurulum kılavuzu

What this is

IQVForge Runner is IQVizyon's self-hosted continuous integration agent. It is a long-running daemon that connects to an IQVForge instance, claims the CI/CD jobs that instance has queued, runs them in Docker containers, and streams the logs and results back.

The two repositories have a clear split:

Repository	Role
IQVForge	The platform: Git hosting, code review, issues, packages, releases, and the web interface where workflows are defined and their results are displayed
IQVForge Runner (this repository)	The CI/CD execution layer: the daemon that picks up queued jobs and actually runs the workflow steps

IQVForge on its own can define and queue workflows, but nothing executes them. A runner has to be registered before the Actions tab produces results.

The command-line program built from this repository is called forgejo-runner. The name is inherited from the upstream project and is used throughout the documentation and in every example command.

How a job runs

1. Someone pushes to a repository on IQVForge that contains a workflow file in .forgejo/workflows/.
2. IQVForge parses the workflow, creates one job per entry under jobs:, and queues each job with the labels requested by runs-on.
3. The runner polls the instance and claims jobs whose labels it declared at registration.
4. For each job the runner creates a container from the image bound to the matching label, then runs the steps inside it.
5. Logs are streamed back to IQVForge while the job runs; the final status appears in the repository's Actions tab.
6. The runner removes the job container and its network, then returns to polling.

Product principles

• Operated and maintained as an IQVizyon product
• Designed to run beside a private, self-hosted IQVForge deployment
• Compatible with Forgejo Actions and existing GitHub Actions-style workflows
• Executes every job in an isolated container, created and destroyed per job
• Maintained with production-grade security, testing, and deployment practices

Requirements

• A reachable IQVForge instance
• Docker Engine 20.10 or newer on Linux, or Docker Desktop with the Linux backend on Windows and macOS
• Roughly 4 GB of memory available to Docker for the initial image build
• A runner registration token from IQVForge

Quick start

This path works the same on Linux, macOS, and Windows. The setup guide covers each platform, native installation from source, and the full configuration reference.

Create a registration token in IQVForge under Site Administration → Actions → Runners.

Copy the environment template and set the token:

cp .env.example .env

On Windows, in PowerShell:

Copy-Item .env.example .env

Edit .env and paste the token into RUNNER_TOKEN. If IQVForge is not running on the same machine, change IQVFORGE_INSTANCE to its URL.

Build the image and start the daemon:

docker compose up -d --build

Confirm the runner connected:

docker compose logs -f iqvforge-runner

A working start ends with the runner declaring its labels and launching the poller:

level=info msg="Starting runner daemon"
level=info msg="runner: iqvforge-runner, with version: v401486e, with labels: [docker], ephemeral: false, declared successfully"
level=info msg="[poller] launched"

The runner now appears as idle in IQVForge under Site Administration → Actions → Runners.

Registration happens once. The result is stored in the iqvforge-runner-data volume, so restarting or rebuilding the container reuses it and does not consume another token.

First workflow

In any IQVForge repository, add .forgejo/workflows/ci.yml:

on: [push]
jobs:
  smoke:
    runs-on: docker
    steps:
      - run: echo "IQVForge Runner works"
      - run: node --version

Push it and open the repository's Actions tab. The first run is the slowest because the runner has to pull the job image.

runs-on: docker matches the label the quick start registers. The label maps to the node:20-bookworm image, which is why node --version works without any setup step.

Labels

A label binds a name that workflows request through runs-on to a backend that runs the job:

Label	Meaning
docker:docker://node:20-bookworm	Jobs using runs-on: docker run in a node:20-bookworm container
ubuntu-latest:docker://node:20-bookworm	Provides the familiar ubuntu-latest name to existing workflows
self-hosted:host	Jobs run directly on the machine, with no container isolation
lxc:lxc://debian:bookworm	Jobs run in an LXC container, on Linux hosts configured for it

Set the labels for the first registration with RUNNER_LABELS in .env. Changing them afterwards is done in config.yml, which is described in the setup guide.

Commands

forgejo-runner provides these subcommands. Run them inside the container with docker compose exec iqvforge-runner forgejo-runner …, or directly if you built from source.

Command	Purpose
daemon	Connect to the instance and run queued jobs continuously
one-job	Run a single job, then exit
register	Register with an instance using a registration token
generate-config	Print a fully commented example configuration file
exec	Run a workflow from a local checkout without any instance
validate	Check workflow or action files against the schema
cache-server	Run the Actions cache server on its own

Development

Building from a checkout needs Go 1.26 or newer, make, and git:

make build

Lint, format, and test:

make lint-check
make lint
make fmt
make test
make integration-test

make test runs the unit tests. make integration-test also runs tests that need Docker or LXC. Individual feature groups can be toggled with go test ./... -args -features "docker,lxc"; passing -features "-" skips all of them.

See the contribution guide.

Supported platforms

The runner is supported and tested on Linux amd64 and arm64. On Windows and macOS, run it through Docker Desktop as shown above; native builds for those systems exist but are not covered by the upstream test suite.

Additional deployment examples, including Kubernetes, LXC with systemd, and Docker-in-Docker, are in examples/.

Upstream and license

IQVForge Runner is a modified distribution based on Forgejo Runner. IQVizyon maintains the product-specific branding, deployment, and integration changes in this repository.

The software remains distributed under the GNU General Public License version 3 or later. Existing copyright and license notices in upstream-derived source files are retained.