Custom Runners

STACKIT Git Pipelines run jobs on runners, which provide the execution environment for your workflows.

In addition to STACKIT managed runners, you can host your own runners on infrastructure you control. Custom runners allow you to run pipeline jobs in environments with specific requirements, such as:

• Access to private networks
• Use of specialized hardware (for example GPUs)
• Execution inside internal infrastructure
• Custom operating system environments

Custom runners are based on the Forgejo runner implementation. For additional configuration details, see the official Forgejo documentation:
https://forgejo.org/docs/v11.0/admin/actions/runner-installation/

Create a custom runner

To use your own infrastructure for pipeline execution, you must install and register a Forgejo runner with your STACKIT Git instance.

1. Download the runner binary

   Download the forgejo-runner binary that matches your operating system from the Forgejo releases.

   Supported platforms include:

   • Linux
   • macOS
   • Windows

   Place the binary on the machine that should execute pipeline jobs.

2. Generate a runner registration token

   • Open your STACKIT Git repository.
   • Navigate to Settings.
   • Select Actions → Runners.
   • Click Create new Runner.

   This generates a registration token that will be used to connect the runner to your repository.

3. Register the runner

   Run the registration command on the machine where the runner is installed.

   ./forgejo-runner register \
   --instance <YOUR_GIT_INSTANCE_URL> \
   --token <YOUR_TOKEN> \
   --name my-custom-runner \
   --labels my-label:host

   Expand

   Parameter	Description
   --instance	URL of your STACKIT Git instance
   --token	Registration token created in the repository settings
   --name	Name used to identify the runner
   --labels	Labels used to select the runner in workflows

4. Start the runner daemon

   Start the runner so it can accept pipeline jobs.

   ./forgejo-runner daemon

   To keep the runner running continuously, it is recommended to run it as a background service using:

   • systemd
   • Docker
   • another process manager

Use the custom runner in a pipeline

After the runner is registered and running, it can execute jobs in your workflows.

To schedule a job on your custom runner, reference its label in the workflow configuration.

Example:

runs-on: my-label

When the pipeline runs, the job is executed on the runner that matches this label.

Next steps

After setting up a custom runner, you can:

• Assign multiple labels for different workloads
• Run pipelines on specialized infrastructure
• Scale runners across multiple machines

For general pipeline configuration and syntax, see the Pipeline Reference documentation.