Aller au contenu
Documentation

Tâches courantes pour Code, Runner Farm et QA

Cette page regroupe une série de recettes succinctes. Chacune d’entre elles permet de résoudre une tâche spécifique à l’aide de commandes que vous pouvez copier. Lorsqu’un script s’avère utile, une --json | jq variante. Pour chaque option d’une commande, consultez les pages de référence : CHAMPREP Code, Runner Farm et CHAMPREP QA.

Dans les exemples, acme est un groupe, acme/web est un projet, et code.champrep.com CodeCHAMPREP.

Fenêtre de terminal
champrep auth login # opens the browser to approve the sign-in
champrep auth whoami # who the CLI acts as
champrep auth list # stored sign-ins, across environments
champrep auth switch PROFILE # make another stored sign-in the active one
champrep --env test code projects ls # one command against the test environment

CHAMPREP Code ne dispose pas de commutateur d’espace de travail distinct. Un projet appartient à un groupe ou à votre espace de noms personnel, et votre rôle au sein de celui-ci détermine ce que vous pouvez faire.

La ferme de runners et l’assurance qualité opèrent dans un espace de travail : votre compte personnel, une organisation ou une équipe. Répertoriez ceux que vous pouvez utiliser, puis transmettez le KEY colonne de rf accounts ls (personal, organization:<id> ou team:<id>) avec --workspace:

Fenêtre de terminal
champrep rf accounts ls # KEY, workspace, your role, whether a farm account exists
champrep org ls # the same organizations and teams (ACCOUNT column)
champrep rf pools ls --workspace organization:65f0c0ffee0000000000abcd
champrep qa repos ls --workspace team:65f0c0ffee0000000000beef

champrep org use NAME définit la valeur par défaut pour les commandes d’organisation telles que business members. Runner Farm et QA l’ignorent. Transmettez --workspace vers ceux-ci, ou laissez le service choisir l’espace de travail comme le fait l’application web.

Fenêtre de terminal
champrep code projects ls --search web
champrep code projects show acme/web # default branch, HTTPS and SSH addresses
champrep code repo clone-url acme/web # HTTPS address
champrep code repo clone-url acme/web --ssh # SSH address
git clone "$(champrep code repo clone-url acme/web --ssh)"

Variante de script :

Fenêtre de terminal
champrep code projects ls --limit 500 --json | jq -r '.[].path_with_namespace'
champrep code projects show acme/web --json | jq -r .ssh_url_to_repo

Git communique directement avec CHAMPREPCode, et non via le serveurCLI, il a donc besoin de ses propres identifiants. CHAMPREPCode n’accepte pas votre identifiant de connexionCLI comme mot de passe Git. La création d’un jeton d’accès personnel ou l’ajout d’une clé SSH constitue une modification des identifiants, ce qui nécessite que vous soyez connecté à votre session Web. Effectuez cette opération une seule fois dans le navigateur.

SSH (recommandé). Cela fonctionne pour tous les projets, et rien n’est stocké en texte clair.

  1. Ouvrir https://code.champrep.com/-/settings/ssh_keys.
  2. Collez votre clé publique, par exemple le contenu de ~/.ssh/id_ed25519.pub.
  3. Vérifiez la clé et la connexion :
Fenêtre de terminal
champrep code ssh-keys ls
git ls-remote git@code.champrep.com:acme/web.git HEAD

HTTPS avec un jeton d’accès personnel.

  1. Ouvrir https://code.champrep.com/-/settings/tokens.
  2. Créez un jeton avec la portée read_repository, ou write_repository si vous effectuez un push. Définissez une date d’expiration.
  3. Configurez le magasin d’identifiants de Git pour qu’il conserve le jeton dans le trousseau de votre système :
Fenêtre de terminal
# macOS
git 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 libsecret

Sous Linux, le libsecret L’utilitaire ne fonctionne que lorsque le git-credential-libsecret Le programme est installé. De nombreuses distributions ne l’installent pas avec Git. Installez-le à partir des paquets de votre distribution, ou compilez-le à partir des sources de Git contrib/credential/libsecret dossier. Vérifiez avec command -v git-credential-libsecret. Si vous ne disposez pas d’un trousseau de clés, évitez l’ store l’utilitaire, qui écrit le jeton dans ~/.git-credentials en texte clair. Utilisez cache --timeout=3600 à la place, qui ne le conserve qu’en mémoire, ou utilisez SSH.

Clonez ensuite un projet manuellement. Git vous demande un nom d’utilisateur (n’importe quelle valeur convient) et un mot de passe (collez le jeton), et le magasin d’identifiants les conserve :

Fenêtre de terminal
git clone https://code.champrep.com/acme/web.git

À partir de ce moment-là, git et champrep code clone utilisez le jeton enregistré. Ne placez jamais de jeton dans une URL distante telle que https://user:TOKEN@…: Git écrit l’URL dans .git/config, et toute personne qui lit ce fichier ou l’historique de votre shell peut l’utiliser . champrep code clone refuse les adresses de clonage contenant des identifiants.

Clonez tous les projets dont vous êtes membre, directement ou via un groupe, dans ~/src. Chaque projet est placé sous son propre espace de noms, par exemple ~/src/acme/platform/api.

Fenêtre de terminal
champrep code clone --membership --dest ~/src --ssh

Autres options :

Fenêtre de terminal
champrep code clone --owned --dest ~/src --ssh # projects where your role is Owner
champrep code clone --all --dest ~/src --ssh # also public and internal projects you can see
champrep code clone acme/web acme/api --dest ~/src # just these projects

Consultez d’abord le plan. Une simulation répertorie chaque projet et ce qui se passerait, sans rien modifier :

Fenêtre de terminal
champrep code clone --membership --dest ~/src --dry-run

Fenêtre de terminal
champrep code clone --group acme --dest ~/src --ssh # the group's own projects
champrep code clone --group acme --include-subgroups --dest ~/src --ssh # and every subgroup
champrep code clone --group acme --include-subgroups --archived --dest ~/src --ssh # archived projects too

--parallel N définit le nombre de clones exécutés simultanément (4 par défaut, 16 au maximum). Les projets archivés sont ignorés, sauf si vous ajoutez --archived. --search TEXT ne conserve que les projets dont le nom ou le chemin d’accès contient le texte.

Relancez la même commande avec --update. Il clone les nouveaux projets et met à jour ceux que vous possédez déjà :

Fenêtre de terminal
champrep code clone --group acme --include-subgroups --dest ~/src --ssh --update

Pour chaque clone existant, --update vérifie d’abord que son origin est le projet, identifié par son adresse HTTPS ou SSH. Un clone d’un autre dépôt situé à ce chemin d’accès est signalé comme mismatch (échec) et laissé tel quel. Il s’exécute ensuite git fetch --prune et une fusion « fast-forward-only » de la branche actuelle. Le travail local n’est jamais écrasé :

  • Une branche qui a divergé est signalée comme ayant échoué, et vous devez la fusionner ou la rebaser vous-même ;
  • Un HEAD détaché ou une branche sans source en amont est simplement récupéré et signalé comme no-upstream.

Sans --update, les clones existants sont ignorés.

La commande s’achève par un résumé, puis se termine 1 En cas d’échec d’un projet, une tâche planifiée peut vous alerter :

Fenêtre de terminal
# crontab: refresh the mirror every night at 02:00
0 2 * * * champrep code clone --group acme --include-subgroups --dest "$HOME/src" --ssh --update >>"$HOME/src/.mirror.log" 2>&1

Variante de script, répertoriant les échecs :

Fenêtre de terminal
champrep code clone --membership --dest ~/src --ssh --update --json \
| jq -r '.[] | select(.status == "failed") | "\(.project): \(.error)"'

Les statuts JSON sont cloned, updated, up_to_date, no_upstream, skipped, failed (avec "reason": "mismatch" (pour le clonage d’un autre dépôt), interrupted et not_started après avoir appuyé sur Ctrl-C, et, avec --dry-run, would_clone, would_update et would_skip.

champrep code clone ne vous demande jamais de confirmation, car plusieurs clonages s’exécutent simultanément. git s’exécute avec GIT_TERMINAL_PROMPT=0. SSH fonctionne avec BatchMode=yes, il ne vous demandera donc ni mot de passe, ni phrase de passe, ni confirmation de la clé hôte, à moins que vous n’en définissiez une vous-même GIT_SSH_COMMAND ou core.sshCommand. Avant un clonage SSH en masse, procédez comme suit : deux étapes :

  1. Chargez votre clé dans ssh-agent (ssh-add).
  2. Connectez-vous une fois manuellement pour accepter la clé de l’hôte (git ls-remote git@code.champrep.com:acme/web.git HEAD).

Un projet nécessitant des identifiants Git ne rencontre aucun échec, que ce soit via could not read Username via HTTPS ou Permission denied (publickey) via SSH. Configurez les identifiants indiqués ci-dessus et relancez la commande.

La combinaison Ctrl-C interrompt l’exécution de manière propre. Aucun nouveau clonage n’est lancé, ceux en cours sont arrêtés (git supprime les clonages inachevés) et le résumé indique ce qui a été effectué. Relancez la commande pour continuer : les clonages terminés sont ignorés.

Seules https:// et les adresses SSH sur l’hôte CodeCHAMPREP sont clonées, et Git s’exécute avec tous les autres protocoles de transport désactivés.

Répertoriez les pipelines et vérifiez le dernier en date sur une branche

Section intitulée « Répertoriez les pipelines et vérifiez le dernier en date sur une branche »
Fenêtre de terminal
champrep code pipelines ls acme/web --limit 10
champrep code pipelines ls acme/web --ref main --limit 1
champrep code pipelines ls acme/web --status failed

Variante de script : afficher l’état du pipeline le plus récent sur main:

Fenêtre de terminal
champrep code pipelines ls acme/web --ref main --limit 1 --json | jq -r '.[0] | "\(.id) \(.status)"'

pipelines wait attend que le pipeline se termine, et son code de sortie constitue le résultat : 0 succès ; 1 a échoué, a été annulé, ignoré ou arrêté lors d’une tâche manuelle ; 8 toujours en cours d’exécution lorsque --timeout (par défaut 60m) s’est épuisé.

Après un push, attendez le pipeline correspondant à la validation que vous avez poussée :

Fenêtre de terminal
git push
champrep code pipelines wait acme/web --sha "$(git rev-parse HEAD)" && ./deploy.sh

--sha attend que Code crée le pipeline de ce commit, puis que celui-ci soit terminé. --sha HEAD Cela fonctionne également à l’intérieur du dépôt. Évitez --ref main juste après un push. Il utilise le pipeline le plus récent présent sur la branche à ce moment-là, qui peut encore être celui du commit précédent si Code n’a pas encore créé celui correspondant à votre push, ce qui vous ferait déployer sur le mauvais résultat.

Fenêtre de terminal
champrep code pipelines wait acme/web --ref main # the newest pipeline on main now
champrep code pipelines wait acme/web 9921 --timeout 30m # one pipeline

Exécutez un pipeline et attendez celui-ci :

Fenêtre de terminal
ID=$(champrep code pipelines run acme/web --ref main --yes --json | jq -r .id)
champrep code pipelines wait acme/web "$ID"

La progression et la ligne d’état finale sont envoyées vers stderr. Avec --json, stdout contient le pipeline terminé, et le code de sortie reste le même :

Fenêtre de terminal
champrep code pipelines wait acme/web "$ID" --json | jq -r '"\(.status) \(.web_url)"'

Un pipeline qui atteint une tâche manuelle, telle qu’un déploiement que vous lancez manuellement, s’arrête à ce stade jusqu’à ce qu’une personne intervienne. pipelines wait sorties 1 accompagné d’un message l’indiquant. Lancez la tâche avec champrep code jobs play, ou transmettre --manual-ok pour considérer le pipeline comme terminé (sortie 0). Une tâche planifiée (différée) démarre automatiquement ; l’attente se poursuit donc pendant son exécution.

Pour surveiller une tâche à la place, suivez son journal. La commande renvoie un résultat lorsque la tâche est terminée et se termine 1 lorsque la tâche a échoué ou a été annulée :

Fenêtre de terminal
champrep code jobs log acme/web 4182 --follow

Fenêtre de terminal
champrep code pipelines retry acme/web 9921 --yes # reruns the failed and canceled jobs
champrep code pipelines cancel acme/web 9921 --yes

Lire le journal d’une tâche ayant échoué, suivre une tâche en cours d’exécution, relancer une tâche

Section intitulée « Lire le journal d’une tâche ayant échoué, suivre une tâche en cours d’exécution, relancer une tâche »
Fenêtre de terminal
champrep code jobs ls acme/web --status failed --limit 5 # newest failed jobs
champrep code jobs ls acme/web --pipeline 9921 --status failed # failed jobs of one pipeline
champrep code jobs log acme/web 4180 --tail 100 # end of a log of any size
champrep code jobs log acme/web 4182 --follow # stream until the job ends
champrep code jobs retry acme/web 4180 --yes # run a finished job again
champrep code jobs play acme/web 4190 --var DEPLOY=staging --yes # start a manual job

Variante de script, affichant les 30 dernières lignes de chaque tâche ayant échoué dans un pipeline :

Fenêtre de terminal
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 30
done

Fenêtre de terminal
git push -u origin feature/login
champrep code mr create acme/web --source feature/login --target main \
--title "Add login page" --remove-source-branch --yes
champrep code mr show acme/web 12 # merge status and head pipeline
champrep code mr approve acme/web 12 --yes
champrep code mr merge acme/web 12 --auto --squash --yes # merges when the pipeline succeeds

Variante de script permettant de récupérer le numéro de la nouvelle demande de fusion :

Fenêtre de terminal
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 --yes

Ce qui nécessite l’application web. Fusionner ou approuver dans un branche protégée C’est une décision que vous seul pouvez prendre, une fois connecté à CodeCHAMPREP dans le navigateur. Le processus s’arrête CLIalors avec needs your web session … (SESSION_REQUIRED) et code de sortie 1. Se reconnecter à la CLI n’y change rien. Ouvrez la demande de fusion dans le navigateur et effectuez la fusion ou l’approbation à partir de là. Les branches non protégées fonctionnent à partir de la CLI.

Runners : liste, voir qui est en ligne, marquer, mettre en pause et reprendre

Section intitulée « Runners : liste, voir qui est en ligne, marquer, mettre en pause et reprendre »
Fenêtre de terminal
champrep code runners ls # project and group runners you manage
champrep 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 now
champrep code runners ls --status offline --active # offline but not paused: worth a look
champrep code runners show 41 # status, online, tags, paused, machines
champrep code runners update 41 --add-tag docker --remove-tag old --yes
champrep code runners update 41 --tags linux,arm64 --yes # replace the whole list
champrep code runners update 41 --pause --yes # stop taking new jobs
champrep code runners update 41 --resume --yes

--add-tag et --remove-tag Lisez les balises du runner et réécrivez la liste complète. Si quelqu’un modifie les balises entre ces deux étapes, sa modification est perdue ; vérifiez donc avec runners show lorsque plusieurs personnes gèrent un runner.

Variante de script : mise en pause de tous les exécuteurs portant une balise avant la maintenance :

Fenêtre de terminal
champrep code runners ls --tag gpu --active --limit 500 --json | jq -r '.[].id' \
| xargs -I{} champrep code runners update {} --pause --yes

Vous devez disposer du rôle « Responsable » pour consulter et modifier les exécuteurs d’un projet, et du rôle « Propriétaire » pour les exécuteurs d’un groupe. Les exécuteurs d’instance sont réservés aux administrateurs d’instance (runners ls --all).

Créer un projet ou un groupe de runners à partir de CLI et y connecter une machine à l’aide de champrep-code-runner. Le jeton (ccrt_…) est affiché une seule fois sur la sortie standard et n’est jamais consigné. Sa création nécessite toujours --yes.

Fenêtre de terminal
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.24

Utilisation --group acme au lieu de --project pour un exécuteur de groupe (vous devez disposer du rôle Propriétaire). Ajouter --no-untagged afin de ne retenir que les tâches balisées, et --protected afin de n’exécuter que les branches et balises protégées. Vous pouvez également créer le runner dans l’application web, sous Paramètres > CI/CD > Exécuteurs du projet ou du groupe. Voir enregistrer un exécuteur.

La CLI ne CLIpeut pas réinitialiser le jeton d’un exécuteur ni créer d’exécuteurs d’instance. Effectuez ces deux opérations dans l’application web.

Fenêtre de terminal
champrep rf accounts show # the farm account, who it bills, the monthly ceiling
champrep rf usage # credits and minutes for the current period
champrep rf usage --period 2026-10 # a past month
champrep rf usage --json # { "balance": …, "usage": …, "period": "YYYY-MM" }

Fenêtre de terminal
champrep rf connections ls
champrep rf pools ls
champrep rf pools show pol_01HZX9K4
champrep rf jobs ls --state waiting,held

Variante de script indiquant le niveau d’activité de chaque pool :

Fenêtre de terminal
champrep rf pools ls --json | jq -r '.pools[] | "\(.id) \(.state) \(.busy)/\(.max_concurrent)"'

Fenêtre de terminal
champrep rf pools update pol_01HZX9K4 --max-concurrent 8 --min-idle 2 --yes # scale up
champrep rf pools update pol_01HZX9K4 --max-concurrent 2 --min-idle 0 --yes # scale down
champrep rf pools update pol_01HZX9K4 --pause --yes # maintenance
champrep rf pools update pol_01HZX9K4 --resume --yes
champrep rf pools create --connection con_01HZX7 --name Builds \
--class build-4 --max-concurrent 4 --timeout 2h --yes # a new pool

--min-idle maintient les exécuteurs « chauds » prêts à l’emploi, ce qui permet aux tâches de démarrer plus rapidement, mais les exécuteurs « chauds » utilisent des crédits. Votre forfait fixe des plafonds pour les classes et les limites que vous pouvez utiliser.

Les jetons des exécuteurs de la ferme d’exécuteurs, les secrets des connecteurs et les appariements restent dans l’application web à l’adresse https://runners.champrep.com. Le CLI ne peut pas y accéder, quelle que soit la clé utilisée.

Fenêtre de terminal
champrep qa repos available --provider code # CHAMPREP Code projects and their QA keys
REPO="code:$(champrep code projects show acme/web --json | jq -r .id)"
champrep qa repos activate "$REPO" --yes

Fenêtre de terminal
champrep qa scan "$REPO" --ref main --watch --yes # exits 1 when the scan or its gate fails
champrep qa scans ls --repo "$REPO" --limit 5

Fenêtre de terminal
champrep qa findings ls --repo "$REPO" --severity critical,high
champrep qa findings ls --severity high --type secret # leaked secrets, whole workspace
champrep qa findings show QA-0970

Variante de script :

Fenêtre de terminal
champrep qa findings ls --repo "$REPO" --severity critical,high --json | jq -r '.[] | "\(.qaId) \(.title)"'

Échec de l’intégration continue en cas de non-respect des critères de qualité

Section intitulée « Échec de l’intégration continue en cas de non-respect des critères de qualité »

champrep qa gates status sorties 1 lorsque le contrôle d’accès échoue, ce qui lui permet de protéger n’importe quelle étape du pipeline. Dans 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"

La même tâche fonctionne dans un GitLab .gitlab-ci.yml. Pour effectuer d’abord une analyse puis un contrôle d’accès, fournissez la clé qa:write et exécutez :

script:
- champrep qa scan "$QA_REPO" --ref "$CI_COMMIT_REF_NAME" --watch --timeout 20m --yes

Une analyse utilise votre quota d’assurance qualité ; c’est pourquoi de nombreuses équipes effectuent des analyses uniquement sur la branche par défaut et les demandes de fusion, et appliquent le contrôle de validation partout ailleurs.

Quelles informations d’identification ? À ne pas utiliser champrep auth login dans CI. Créez une clé à portée API limitée lorsque vous êtes connecté à la CLI dansCLI une session de navigateur, puis enregistrez-la sous la forme d’une variable CI masquée et protégée nommée CHAMPREP_TOKEN. La CLI utilise cette variable à la place du trousseau de clés.

Fenêtre de terminal
champrep keys create --name "CI: acme/web" --scope code:read_api --scope qa:read --expires-in-days 90
Ce que fait la tâchePortées
Lecture du code : projets, pipelines, journaux de tâches, exécuteurscode:read_api
Modifier le code : exécuter des pipelines, réessayer des tâches, ouvrir et fusionner des MR, mettre à jour les runnerscode:api
Consultez la section « Runner Farm » / « Modifier les pools »runner_farm:read / runner_farm:write
Vérifier les contrôles de qualité et les résultats / lancer des analyses, activer les dépôtsqa:read / qa:write

N’accordez que les autorisations nécessaires à la tâche. Une clé ne peut pas accéder à l’administration de CodeCHAMPREP, aux identifiants de Runner Farm, ni à tout élément nécessitant votre session Web. session.

Aucune invite. Sans terminal, toute commande qui modifie quelque chose est refusée, sauf si vous lui transmettez --yes (-y), et rien n’est envoyé. Ajoutez --yes à chaque écriture dans un script. champrep code clone ne demande jamais de confirmation et ne nécessite aucune --yes.

Sortie lisible par machine. Ajouter --json et analysez-le avec jq. Le code de sortie reste le même avec --json. N’analysez pas le texte lisible par l’utilisateur.

Codes de sortie.

CodeSignificationAction type en CI
0Succès.Continuer.
1Échec ou refus : une étape qui a échoué, une analyse qui a échoué, un pipeline ou une tâche suivie qui n’a pas abouti, un clonage qui a échoué, aucun accès à l’élément, non inclus dans votre forfait, votre rôle, une décision nécessitant votre session Web, ou un fichier manquant --yes.Le job a échoué ; lisez le message.
3Vous n’êtes pas connecté, ou la clé n’est pas valide ou a été révoquée.Corriger CHAMPREP_TOKEN.
4La clé ne dispose pas de champ d’application.Ajoutez la portée à la clé.
5Limite de débit ou capacité.Réessayez plus tard.
6Panne réseau.Réessayez.
7Défaillance de la passerelle ou du service.Réessayez plus tard.
8pipelines wait à court de --timeout; le pipeline est toujours en cours d’exécution.Patientez à nouveau ou signalez un incident --timeout.

Consultez le Référence des commandes et API Clés pour l’automatisation.