Register a runner
Registering connects a machine to a runner you created in CHAMPREP Code. You
need the runner’s authentication token, which starts with ccrt_.
1. Create the runner in CHAMPREP Code
Section titled “1. Create the runner in CHAMPREP Code”- Open your project (or group) and go to Settings > CI/CD > Runners.
- Select New runner.
- Choose which jobs it takes:
- Tags: jobs with
tags:run only on runners that have all of them. - Run untagged jobs: whether it also takes jobs without tags.
- Protected: run only jobs of protected branches and tags.
- Tags: jobs with
- Select Create runner and copy the token. It is shown once.
Treat the token like a password. Anyone who has it can take your jobs.
2. Register the machine
Section titled “2. Register the machine”The simplest way, in a terminal on the machine:
champrep-code-runner register --url https://code.champrep.comThe runner asks for the token (without showing it) and the executor. It checks the token, then saves the runner in its configuration file.
To script it, pass the token on standard input or from a file, so it never appears in your shell history or the process list:
printf '%s\n' "$RUNNER_TOKEN" | champrep-code-runner register \ --url https://code.champrep.com --token-stdin \ --name build-01 --executor shellchamprep-code-runner register --url https://code.champrep.com \ --token-file /root/runner-token --executor docker --docker-image alpine:3.24On Windows, from an elevated PowerShell prompt:
$env:RUNNER_TOKEN | champrep-code-runner.exe register ` --url https://code.champrep.com --token-stdin --name win-build-01 ` --executor shell --shell pwshCommon options
Section titled “Common options”| Option | Meaning |
|---|---|
--url | Your CHAMPREP Code address, for example https://code.champrep.com. |
--token-stdin / --token-file PATH | Read the token from standard input or a file. |
--name NAME | The runner’s name on this machine (default: the host name). |
--executor | shell, docker or kubernetes. |
--shell | For the shell executor: bash, sh, pwsh or powershell. |
--docker-image IMAGE | Default job image for the Docker and Kubernetes executors. |
--kubernetes-namespace NS | Run Kubernetes jobs in this namespace. |
--limit N | At most N jobs at once for this runner. |
--non-interactive | Never prompt; fail if a value is missing. |
--config PATH | Use this configuration file (see below). |
CHPCODE_RUNNER_URL and CHPCODE_RUNNER_TOKEN can replace --url and the
token options.
Where the configuration is saved
Section titled “Where the configuration is saved”| When you run it as | File |
|---|---|
| root (Linux, macOS) | /etc/champrep-runner/config.toml |
| An elevated prompt or the service (Windows) | %ProgramData%\champrep-runner\config.toml |
| Any other user | ~/.champrep-runner/config.toml |
CHPCODE_RUNNER_CONFIG or --config choose another file. The file is created
readable only by its owner. One machine can hold several runners: register again
with a different --name.
3. Start it
Section titled “3. Start it”champrep-code-runner run # in this terminalchamprep-code-runner service install # or as a service that starts at bootSee Runner commands to check its status, stop it, and more.