Common tasks for Code, Runner Farm and QA
This page is a set of short recipes. Each one solves a single task with
commands you can copy. Where a script helps, there is a --json | jq variant.
For every flag of a command, see the reference pages:
CHAMPREP Code, Runner Farm and
CHAMPREP QA.
In the examples, acme is a group, acme/web is a project, and
code.champrep.com is CHAMPREP Code.
Sign in and pick an account
Section titled “Sign in and pick an account”champrep auth login # opens the browser to approve the sign-inchamprep auth whoami # who the CLI acts aschamprep auth list # stored sign-ins, across environmentschamprep auth switch PROFILE # make another stored sign-in the active onechamprep --env test code projects ls # one command against the test environmentCHAMPREP Code has no separate workspace switch. A project belongs to a group or to your personal namespace, and your role in it decides what you can do.
Runner Farm and QA act in a workspace: your personal account, an
organization or a team. List the ones you can use, then pass the KEY column
of rf accounts ls (personal, organization:<id> or team:<id>) with
--workspace:
champrep rf accounts ls # KEY, workspace, your role, whether a farm account existschamprep org ls # the same organizations and teams (ACCOUNT column)champrep rf pools ls --workspace organization:65f0c0ffee0000000000abcdchamprep qa repos ls --workspace team:65f0c0ffee0000000000beefchamprep org use NAME sets the default for organization commands such as
business members. Runner Farm and QA ignore it. Pass --workspace to
them, or let the service pick the workspace the way the web app does.
CHAMPREP Code
Section titled “CHAMPREP Code”Find a project and its clone address
Section titled “Find a project and its clone address”champrep code projects ls --search webchamprep code projects show acme/web # default branch, HTTPS and SSH addresseschamprep code repo clone-url acme/web # HTTPS addresschamprep code repo clone-url acme/web --ssh # SSH addressgit clone "$(champrep code repo clone-url acme/web --ssh)"Scripting variant:
champrep code projects ls --limit 500 --json | jq -r '.[].path_with_namespace'champrep code projects show acme/web --json | jq -r .ssh_url_to_repoSet up git credentials
Section titled “Set up git credentials”git talks to CHAMPREP Code directly, not through the CLI, so it needs its own credential. CHAMPREP Code does not accept your CLI sign-in as a git password. Creating a personal access token or adding an SSH key is a credential change, so it needs your signed-in web session. Do it once in the browser.
SSH (recommended). It works for every project, and nothing is stored in plain text.
- Open
https://code.champrep.com/-/settings/ssh_keys. - Paste your public key, for example the contents of
~/.ssh/id_ed25519.pub. - Check the key and the connection:
champrep code ssh-keys lsgit ls-remote git@code.champrep.com:acme/web.git HEADHTTPS with a personal access token.
- Open
https://code.champrep.com/-/settings/tokens. - Create a token with the scope
read_repository, orwrite_repositoryif you push. Give it an expiry date. - Let git’s credential store keep the token in your system keychain:
# macOSgit config --global credential.https://code.champrep.com.helper osxkeychain# Windows (Git Credential Manager)git config --global credential.https://code.champrep.com.helper manager# Linux with libsecret (needs git-credential-libsecret, see below)git config --global credential.https://code.champrep.com.helper libsecretOn Linux, the libsecret helper works only when the git-credential-libsecret
program is installed. Many distributions do not install it with git. Install
it from your distribution’s packages, or build it from git’s
contrib/credential/libsecret folder. Check with
command -v git-credential-libsecret. Without a keyring, avoid the store
helper, which writes the token to ~/.git-credentials in plain text. Use
cache --timeout=3600 instead, which keeps it in memory only, or use SSH.
Then clone one project by hand. git asks for a user name (any value works) and a password (paste the token), and the credential store keeps them:
git clone https://code.champrep.com/acme/web.gitFrom then on, git and champrep code clone use the stored token. Never put a
token in a remote URL such as https://user:TOKEN@…: git writes the URL to
.git/config, and anyone who reads that file or your shell history can use
it. champrep code clone refuses clone addresses that carry a credential.
Clone all my projects
Section titled “Clone all my projects”Clone every project you are a member of, directly or through a group, into
~/src. Each project lands under its namespace, for example
~/src/acme/platform/api.
champrep code clone --membership --dest ~/src --sshOther choices:
champrep code clone --owned --dest ~/src --ssh # projects where your role is Ownerchamprep code clone --all --dest ~/src --ssh # also public and internal projects you can seechamprep code clone acme/web acme/api --dest ~/src # just these projectsSee the plan first. A dry run lists each project and what would happen, without touching anything:
champrep code clone --membership --dest ~/src --dry-runClone one group, with its subgroups
Section titled “Clone one group, with its subgroups”champrep code clone --group acme --dest ~/src --ssh # the group's own projectschamprep code clone --group acme --include-subgroups --dest ~/src --ssh # and every subgroupchamprep code clone --group acme --include-subgroups --archived --dest ~/src --ssh # archived projects too--parallel N sets how many clones run at once (default 4, at most 16).
Archived projects are left out unless you add --archived. --search TEXT
keeps only projects whose name or path contains the text.
Keep a local mirror up to date
Section titled “Keep a local mirror up to date”Run the same command again with --update. It clones new projects and
updates the ones you already have:
champrep code clone --group acme --include-subgroups --dest ~/src --ssh --updateFor each existing clone, --update first checks that its origin is the
project, by its HTTPS or SSH address. A clone of another repository at that
path is reported as mismatch (failed) and left alone. Then it runs
git fetch --prune and a fast-forward-only merge of the current branch.
Local work is never overwritten:
- a branch that has diverged is reported as failed, and you merge or rebase it yourself;
- a detached HEAD or a branch without an upstream is fetched only and reported
as
no-upstream.
Without --update, existing clones are skipped.
The command ends with a summary and exits 1 when any project failed, so a
scheduled job can alert you:
# crontab: refresh the mirror every night at 02:000 2 * * * champrep code clone --group acme --include-subgroups --dest "$HOME/src" --ssh --update >>"$HOME/src/.mirror.log" 2>&1Scripting variant, listing what failed:
champrep code clone --membership --dest ~/src --ssh --update --json \ | jq -r '.[] | select(.status == "failed") | "\(.project): \(.error)"'The JSON statuses are cloned, updated, up_to_date, no_upstream,
skipped, failed (with "reason": "mismatch" for a clone of another
repository), interrupted and not_started after Ctrl-C, and, with
--dry-run, would_clone, would_update and would_skip.
champrep code clone never prompts, because several clones run at once.
git runs with GIT_TERMINAL_PROMPT=0. SSH runs with BatchMode=yes, so it
asks no password, passphrase or host-key question, unless you set your own
GIT_SSH_COMMAND or core.sshCommand. Before a bulk SSH clone, do two
things:
- Load your key in
ssh-agent(ssh-add). - Connect once by hand to accept the host key (
git ls-remote git@code.champrep.com:acme/web.git HEAD).
A project that needs a credential git does not have fails, with
could not read Username over HTTPS or Permission denied (publickey) over
SSH. Set up the credentials above and run the command again.
Ctrl-C stops the run cleanly. No new clones start, the running ones are stopped (git removes a half-finished clone), and the summary shows what was done. Run the command again to continue: finished clones are skipped.
Only https:// and SSH addresses on the CHAMPREP Code host are cloned, and
git runs with every other transport disabled.
List pipelines and check the latest one on a branch
Section titled “List pipelines and check the latest one on a branch”champrep code pipelines ls acme/web --limit 10champrep code pipelines ls acme/web --ref main --limit 1champrep code pipelines ls acme/web --status failedScripting variant, printing the status of the newest pipeline on main:
champrep code pipelines ls acme/web --ref main --limit 1 --json | jq -r '.[0] | "\(.id) \(.status)"'Wait for a pipeline
Section titled “Wait for a pipeline”pipelines wait waits until a pipeline finishes, and its exit code is the
outcome: 0 success; 1 failed, canceled, skipped, or stopped at a manual
job; 8 still running when --timeout (default 60m) ran out.
After a push, wait for the pipeline of the commit you pushed:
git pushchamprep code pipelines wait acme/web --sha "$(git rev-parse HEAD)" && ./deploy.sh--sha waits for Code to create that commit’s pipeline, then for it to
finish. --sha HEAD also works inside the repository. Avoid --ref main
right after a push. It takes the newest pipeline on the branch at that
moment, which can still be the previous commit’s pipeline if Code has not yet
created the one for your push, and you would deploy on the wrong result.
champrep code pipelines wait acme/web --ref main # the newest pipeline on main nowchamprep code pipelines wait acme/web 9921 --timeout 30m # one pipelineRun a pipeline and wait for that one:
ID=$(champrep code pipelines run acme/web --ref main --yes --json | jq -r .id)champrep code pipelines wait acme/web "$ID"Progress and the final status line go to stderr. With --json, stdout holds
the finished pipeline, and the exit code stays the same:
champrep code pipelines wait acme/web "$ID" --json | jq -r '"\(.status) \(.web_url)"'A pipeline that reaches a manual job, such as a deploy you start by hand,
stops there until a person acts. pipelines wait exits 1 with a message
saying so. Start the job with champrep code jobs play, or pass
--manual-ok to count the pipeline as finished (exit 0). A scheduled
(delayed) job starts on its own, so the wait goes on through it.
To watch one job instead, follow its log. The command returns when the job
finishes and exits 1 when the job failed or was canceled:
champrep code jobs log acme/web 4182 --followRetry or cancel a pipeline
Section titled “Retry or cancel a pipeline”champrep code pipelines retry acme/web 9921 --yes # reruns the failed and canceled jobschamprep code pipelines cancel acme/web 9921 --yesRead a failed job’s log, follow a running job, rerun a job
Section titled “Read a failed job’s log, follow a running job, rerun a job”champrep code jobs ls acme/web --status failed --limit 5 # newest failed jobschamprep code jobs ls acme/web --pipeline 9921 --status failed # failed jobs of one pipelinechamprep code jobs log acme/web 4180 --tail 100 # end of a log of any sizechamprep code jobs log acme/web 4182 --follow # stream until the job endschamprep code jobs retry acme/web 4180 --yes # run a finished job againchamprep code jobs play acme/web 4190 --var DEPLOY=staging --yes # start a manual jobScripting variant, printing the last 30 lines of every failed job in a pipeline:
for J in $(champrep code jobs ls acme/web --pipeline 9921 --status failed --json | jq -r '.[].id'); do echo "=== job $J" champrep code jobs log acme/web "$J" --tail 30doneOpen a merge request and merge it
Section titled “Open a merge request and merge it”git push -u origin feature/loginchamprep code mr create acme/web --source feature/login --target main \ --title "Add login page" --remove-source-branch --yeschamprep code mr show acme/web 12 # merge status and head pipelinechamprep code mr approve acme/web 12 --yeschamprep code mr merge acme/web 12 --auto --squash --yes # merges when the pipeline succeedsScripting variant, capturing the new merge request’s number:
IID=$(champrep code mr create acme/web --source feature/login --target main \ --title "Add login page" --yes --json | jq -r .iid)champrep code mr merge acme/web "$IID" --auto --yesWhat needs the web app. Merging or approving into a protected branch
is a decision only you can take, signed in to CHAMPREP Code in the browser.
The CLI then stops with needs your web session … (SESSION_REQUIRED) and exit
code 1. Signing in to the CLI again does not change that. Open the merge
request in the browser and merge or approve it there. Unprotected branches
work from the CLI.
Runners: list, see who is online, tag, pause and resume
Section titled “Runners: list, see who is online, tag, pause and resume”champrep code runners ls # project and group runners you managechamprep code runners ls --project acme/web # runners the project can use (Maintainer)champrep code runners ls --group acme # the group's runners (Owner)champrep code runners ls --status online # who is online nowchamprep code runners ls --status offline --active # offline but not paused: worth a lookchamprep code runners show 41 # status, online, tags, paused, machineschamprep code runners update 41 --add-tag docker --remove-tag old --yeschamprep code runners update 41 --tags linux,arm64 --yes # replace the whole listchamprep code runners update 41 --pause --yes # stop taking new jobschamprep code runners update 41 --resume --yes--add-tag and --remove-tag read the runner’s tags and write the whole
list back. If someone changes the tags between those two steps, their change
is lost, so check with runners show when several people manage a runner.
Scripting variant, pausing every runner with a tag before maintenance:
champrep code runners ls --tag gpu --active --limit 500 --json | jq -r '.[].id' \ | xargs -I{} champrep code runners update {} --pause --yesYou need Maintainer to see and change a project’s runners, and Owner for a
group’s runners. Instance runners are for instance administrators
(runners ls --all).
Register a runner
Section titled “Register a runner”Create a project or group runner from the CLI and connect a machine to it with
champrep-code-runner. The token (ccrt_…) is printed once, on standard
output, and never logged. Creating it always needs --yes.
champrep code runners create --project acme/web --description "build box" \ --tags linux,docker --yes --json \ | jq -r .token \ | champrep-code-runner register --url https://code.champrep.com --token-stdin \ --executor docker --docker-image alpine:3.24Use --group acme instead of --project for a group runner (you need Owner).
Add --no-untagged to take only tagged jobs, and --protected to run only
protected branches and tags. You can also create the runner in the web app,
under Settings > CI/CD > Runners of the project or group. See
register a runner.
The CLI cannot reset a runner’s token or create instance runners. Do both in the web app.
Runner Farm
Section titled “Runner Farm”Check usage and credits
Section titled “Check usage and credits”champrep rf accounts show # the farm account, who it bills, the monthly ceilingchamprep rf usage # credits and minutes for the current periodchamprep rf usage --period 2026-10 # a past monthchamprep rf usage --json # { "balance": …, "usage": …, "period": "YYYY-MM" }See pools and what is waiting
Section titled “See pools and what is waiting”champrep rf connections lschamprep rf pools lschamprep rf pools show pol_01HZX9K4champrep rf jobs ls --state waiting,heldScripting variant, showing how busy each pool is:
champrep rf pools ls --json | jq -r '.pools[] | "\(.id) \(.state) \(.busy)/\(.max_concurrent)"'Scale a pool
Section titled “Scale a pool”champrep rf pools update pol_01HZX9K4 --max-concurrent 8 --min-idle 2 --yes # scale upchamprep rf pools update pol_01HZX9K4 --max-concurrent 2 --min-idle 0 --yes # scale downchamprep rf pools update pol_01HZX9K4 --pause --yes # maintenancechamprep rf pools update pol_01HZX9K4 --resume --yeschamprep rf pools create --connection con_01HZX7 --name Builds \ --class build-4 --max-concurrent 4 --timeout 2h --yes # a new pool--min-idle keeps warm runners ready, so jobs start faster, but warm runners
use credits. Your plan caps the classes and limits you can use.
Runner Farm runner tokens, connector secrets and pairing stay in the web app
at https://runners.champrep.com. The CLI cannot reach them, for any key.
CHAMPREP QA
Section titled “CHAMPREP QA”Activate a repository
Section titled “Activate a repository”champrep qa repos available --provider code # CHAMPREP Code projects and their QA keysREPO="code:$(champrep code projects show acme/web --json | jq -r .id)"champrep qa repos activate "$REPO" --yesScan and wait for the result
Section titled “Scan and wait for the result”champrep qa scan "$REPO" --ref main --watch --yes # exits 1 when the scan or its gate failschamprep qa scans ls --repo "$REPO" --limit 5List high-severity findings
Section titled “List high-severity findings”champrep qa findings ls --repo "$REPO" --severity critical,highchamprep qa findings ls --severity high --type secret # leaked secrets, whole workspacechamprep qa findings show QA-0970Scripting variant:
champrep qa findings ls --repo "$REPO" --severity critical,high --json | jq -r '.[] | "\(.qaId) \(.title)"'Fail CI on a failing quality gate
Section titled “Fail CI on a failing quality gate”champrep qa gates status exits 1 when the gate fails, so it can guard any
pipeline step. In CHAMPREP Code (.chpcode-ci.yml):
qa-gate: stage: test image: alpine:3.20 variables: QA_REPO: "code:7d0c5c6e-0b6a-4e2b-9a55-0f8e6c1d2a10" before_script: - apk add --no-cache curl - curl -fsSL https://cli.champrep.com/install.sh | sh - export PATH="$HOME/.local/bin:$PATH" script: # CHAMPREP_TOKEN is a masked, protected CI variable holding an API key # with the qa:read scope. - champrep qa gates status "$QA_REPO" --branch "$CI_COMMIT_REF_NAME"The same job works in a GitLab .gitlab-ci.yml. To scan first and then
gate, give the key qa:write as well and run:
script: - champrep qa scan "$QA_REPO" --ref "$CI_COMMIT_REF_NAME" --watch --timeout 20m --yesA scan uses your QA allowance, so many teams scan on the default branch and merge requests only, and check the gate everywhere else.
Using the CLI in CI and scripts
Section titled “Using the CLI in CI and scripts”Which credential. Do not use champrep auth login in CI. Create a scoped
API key while signed in to the CLI in a browser session, and store it as a
masked, protected CI variable named CHAMPREP_TOKEN. The CLI uses that
variable instead of the keychain.
champrep keys create --name "CI: acme/web" --scope code:read_api --scope qa:read --expires-in-days 90| What the job does | Scopes |
|---|---|
| Read Code: projects, pipelines, job logs, runners | code:read_api |
| Change Code: run pipelines, retry jobs, open and merge MRs, update runners | code:api |
| Read Runner Farm / change pools | runner_farm:read / runner_farm:write |
| Check QA gates and findings / start scans, activate repositories | qa:read / qa:write |
Grant only what the job needs. A key cannot reach CHAMPREP Code administration, Runner Farm credentials, or anything that needs your web session.
No prompts. Without a terminal, any command that changes something
refuses unless you pass --yes (-y), and nothing is sent. Add --yes to
every write in a script. champrep code clone never prompts and needs no
--yes.
Machine-readable output. Add --json and parse it with jq. The exit
code stays the same with --json. Do not parse the human-readable text.
Exit codes.
| Code | Meaning | Typical action in CI |
|---|---|---|
0 | Success. | Continue. |
1 | Failure or refusal: a failing gate, a failed scan, a pipeline or followed job that did not succeed, a clone that failed, no access to the item, not on your plan, your role, a decision that needs your web session, or a missing --yes. | Fail the job; read the message. |
3 | Not signed in, or the key is invalid or revoked. | Fix CHAMPREP_TOKEN. |
4 | The key lacks a scope. | Add the scope to the key. |
5 | Rate limit or capacity. | Retry later. |
6 | Network failure. | Retry. |
7 | Gateway or service failure. | Retry later. |
8 | pipelines wait ran out of --timeout; the pipeline is still running. | Wait again, or raise --timeout. |
See the command reference and API keys for automation.