Ir al contenido
Documentation

Tareas comunes para Code, Runner Farm y QA

Esta página recoge una serie de recetas breves. Cada una de ellas resuelve una única tarea mediante comandos que puede copiar. Cuando un script resulta útil, hay una --json | jq variante. Para cada opción de un comando, consulte las páginas de referencia: CHAMPREP Código, Runner Farm y CHAMPREP QA.

En los ejemplos, acme es un grupo, acme/web es un proyecto, y code.champrep.com es CHAMPREP Código.

Ventana 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 no dispone de un cambio de espacio de trabajo independiente. Un proyecto pertenece a un grupo o a su espacio de nombres personal, y su rol en él determina lo que puede hacer.

Runner Farm y QA operan en un espacio de trabajo: su cuenta personal, una organización o un equipo. Enumere aquellos que pueda utilizar y, a continuación, introduzca el KEY columna de rf accounts ls (personal, organization:<id> o team:<id>) con --workspace:

Ventana 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 establece el valor por defecto para los comandos de la organización, como business members. Runner Farm y QA lo ignoran. Pase --workspace en ellos, o deje que el servicio elija el espacio de trabajo tal y como lo hace la aplicación web.

Busque un proyecto y su dirección de clonación

Sección titulada «Busque un proyecto y su dirección de clonación»
Ventana 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:

Ventana 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 se comunica directamente con CHAMPREPCode, no a través de CLI, por lo que necesita su propia credencial. CHAMPREPCode no acepta su CLIinicio de sesión como contraseña de Git. Crear un token de acceso personal o añadir una clave SSH supone un cambio de credenciales, por lo que requiere que esté conectado a la sesión web. Hágalo una sola vez en el navegador.

SSH (recomendado). Funciona para todos los proyectos y no se almacena nada en texto sin cifrar.

  1. Abrir https://code.champrep.com/-/settings/ssh_keys.
  2. Pegue su clave pública, por ejemplo, el contenido de ~/.ssh/id_ed25519.pub.
  3. Compruebe la clave y la conexión:
Ventana de terminal
champrep code ssh-keys ls
git ls-remote git@code.champrep.com:acme/web.git HEAD

HTTPS con un token de acceso personal.

  1. Abrir https://code.champrep.com/-/settings/tokens.
  2. Cree un token con el ámbito read_repository, o write_repository si realiza un «push». Establezca una fecha de caducidad.
  3. Deje que el almacén de credenciales de Git guarde el token en el llavero de su sistema:
Ventana 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

En Linux, el libsecret La herramienta auxiliar solo funciona cuando el git-credential-libsecret El programa está instalado. Muchas distribuciones no lo instalan junto con Git. Instálelo a partir de los paquetes de su distribución o compílelo desde el código de Git contrib/credential/libsecret carpeta. Compruébelo con command -v git-credential-libsecret. Si no dispone de un llavero, evite el store ayudante, que escribe el token en ~/.git-credentials en texto sin cifrar. Utilice cache --timeout=3600 en su lugar, que lo mantiene únicamente en memoria, o utilice SSH.

A continuación, clone un proyecto manualmente. Git le pedirá un nombre de usuario (cualquier valor es válido) y una contraseña (pegue el token), y el almacén de credenciales los guardará:

Ventana de terminal
git clone https://code.champrep.com/acme/web.git

A partir de ese momento, git y champrep code clone utilice el token almacenado. Nunca incluya un token en una URL remota como https://user:TOKEN@…: Git escribe la URL en .git/config, y cualquiera que lea ese archivo o su historial de shell podrá utilizarlo . champrep code clone rechaza las direcciones de clonación que contengan una credencial.

Clone todos los proyectos de los que sea miembro, ya sea directamente o a través de un grupo, en ~/src. Cada proyecto se aloja en su propio espacio de nombres, por ejemplo ~/src/acme/platform/api.

Ventana de terminal
champrep code clone --membership --dest ~/src --ssh

Otras opciones:

Ventana 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

Consulte primero el plan. Una simulación enumera cada proyecto y lo que sucedería, sin modificar nada:

Ventana de terminal
champrep code clone --membership --dest ~/src --dry-run

Ventana 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 establece el número de clones que se ejecutan a la vez (por defecto 4, como máximo 16). Los proyectos archivados quedan excluidos a menos que añada --archived. --search TEXT Solo se conservan los proyectos cuyo nombre o ruta contengan el texto.

Ejecute de nuevo el mismo comando con --update. Clona nuevos proyectos y actualiza los que ya tiene:

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

Para cada clon existente, --update primero comprueba que su origin es el proyecto, mediante su dirección HTTPS o SSH. Un clon de otro repositorio en esa ruta se indica como mismatch (falló) y se dejó tal cual. A continuación, se ejecuta git fetch --prune y una fusión «fast-forward-only» de la rama actual. El trabajo local nunca se sobrescribe:

  • una rama que se haya desviado se marca como fallida, y deberá fusionarla o rebasarla usted mismo;
  • Un HEAD desvinculado o una rama sin un upstream solo se recupera y se notifica como no-upstream.

Sin --update, se omiten los clones existentes.

El comando finaliza con un resumen y se cierra 1 Cuando falle algún proyecto, una tarea programada podrá avisarle:

Ventana 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 mediante script, con un listado de lo que ha fallado:

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

Los estados en formato JSON son cloned, updated, up_to_date, no_upstream, skipped, failed (con "reason": "mismatch" (para clonar otro repositorio), interrupted y not_started tras pulsar Ctrl-C, y, con --dry-run, would_clone, would_update y would_skip.

champrep code clone Nunca solicita información, ya que se ejecutan varios clonados a la vez. git se ejecuta con GIT_TERMINAL_PROMPT=0. SSH se ejecuta con BatchMode=yes, por lo que no solicita contraseña, frase de acceso ni verificación de la clave del host, a menos que usted configure las suyas propias GIT_SSH_COMMAND o core.sshCommand. Antes de realizar una clonación masiva por SSH, haga dos cosas:

  1. Cargue su clave en ssh-agent (ssh-add).
  2. Conéctese una vez manualmente para aceptar la clave del host (git ls-remote git@code.champrep.com:acme/web.git HEAD).

Un proyecto que requiera una credencial que Git no disponga falla, ya sea a través de could not read Username a través de HTTPS o Permission denied (publickey) a través de SSH. Configure las credenciales indicadas anteriormente y vuelva a ejecutar el comando.

Pulsar Ctrl-C detiene la ejecución de forma limpia. No se inician nuevos clonados, los que están en curso se detienen (git elimina los clonados a medio realizar) y el resumen muestra lo que se ha realizado. Ejecute el comando de nuevo para continuar: los clonados finalizados se omiten.

Solo https:// y las direcciones SSH en el host de CodeCHAMPREP se clonan, y git se ejecuta con todos los demás medios de transporte desactivados.

Enumere los pipelines y compruebe cuál es el más reciente en una rama

Sección titulada «Enumere los pipelines y compruebe cuál es el más reciente en una rama»
Ventana 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: mostrar el estado del pipeline más reciente en main:

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

pipelines wait espera hasta que finalice una pipeline, y su código de salida es el resultado: 0 éxito; 1 ha fallado, se ha cancelado, se ha omitido o se ha detenido en una tarea manual; 8 sigue en ejecución cuando --timeout (por defecto 60m) se ha agotado.

Tras un «push», espere a que se ejecute el pipeline de la confirmación que ha enviado:

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

--sha espera a que Code cree el pipeline de esa confirmación y, a continuación, a que finalice. --sha HEAD También funciona dentro del repositorio. Evite --ref main inmediatamente después de un push. Toma el pipeline más reciente de la rama en ese momento, que aún puede ser el pipeline de la confirmación anterior si Code aún no ha creado el correspondiente a su push, y usted acabaría implementando el resultado incorrecto.

Ventana 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

Ejecute un pipeline y espere a que se complete:

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

El progreso y la línea de estado final se envían a stderr. Con --json, stdout contiene el pipeline finalizado, y el código de salida permanece igual:

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

Un pipeline que llega a una tarea manual, como una implementación que se inicia manualmente, se detiene ahí hasta que una persona actúe. pipelines wait salidas 1 con un mensaje que lo indique. Inicie el trabajo con champrep code jobs play, o pasar --manual-ok para considerar el pipeline como finalizado (salir 0). Una tarea programada (diferida) se inicia por sí sola, por lo que la espera continúa mientras se ejecuta.

Para supervisar un trabajo en concreto, siga su registro. El comando finaliza cuando el trabajo termina y se cierra 1 cuando el trabajo haya fallado o se haya cancelado:

Ventana de terminal
champrep code jobs log acme/web 4182 --follow

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

Lea el registro de un trabajo fallido, siga un trabajo en ejecución, vuelva a ejecutar un trabajo

Sección titulada «Lea el registro de un trabajo fallido, siga un trabajo en ejecución, vuelva a ejecutar un trabajo»
Ventana 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: mostrar las últimas 30 líneas de cada trabajo fallido en un pipeline:

Ventana 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

Ventana 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, capturando el número de la nueva solicitud de fusión:

Ventana 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

Lo que requiere la aplicación web. Fusionar o aprobar en una rama protegida Es una decisión que solo usted puede tomar, tras iniciar sesión en CodeCHAMPREP en el navegador. A continuaciónCLI, el proceso se detiene con needs your web session … (SESSION_REQUIRED) y código de salida 1. VolverCLI a iniciar sesión en la CLI no cambia esta situación. Abra la solicitud de fusión en el navegador y fúndala o apruébela desde allí. Las ramas sin protección funcionan desde la CLICLI.

Ejecutores: listar, ver quién está conectado, etiquetar, pausar y reanudar

Sección titulada «Ejecutores: listar, ver quién está conectado, etiquetar, pausar y reanudar»
Ventana 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 y --remove-tag Lea las etiquetas del ejecutor y vuelva a escribir la lista completa. Si alguien modifica las etiquetas entre esos dos pasos, su cambio se perderá, por lo que debe comprobarlo con runners show cuando varias personas gestionan un ejecutor.

Variante de script: poner en pausa todos los ejecutores con una etiqueta antes del mantenimiento:

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

Necesita el rol de «Mantenedor» para ver y modificar los ejecutores de un proyecto, y el de «Propietario» para los ejecutores de un grupo. Los ejecutores de instancia están destinados a los administradores de instancia (runners ls --all).

Crear un proyecto o un ejecutor de grupo desde el CLI y conectar una máquina al mismo con champrep-code-runner. El token (ccrt_…) se imprime una sola vez en la salida estándar y nunca se registra. Para crearla siempre es necesario --yes.

Ventana 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

Utilizar --group acme en lugar de --project para un ejecutor de grupo (necesita ser propietario). Añadir --no-untagged para seleccionar únicamente los trabajos etiquetados, y --protected para ejecutar únicamente ramas y etiquetas protegidas. También puede crear el ejecutor en la aplicación web, en Configuración > CI/CD > Ejecutores del proyecto o grupo. Véase registrar un ejecutor.

La CLI noCLI puede restablecer el token de un ejecutor ni crear ejecutores de instancia. Realice ambas acciones en la aplicación web.

Ventana 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" }

Ventana 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 que muestra el nivel de ocupación de cada grupo:

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

Ventana 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 mantiene listos los ejecutores «en espera», para que los trabajos se inicien más rápido, pero los ejecutores «en espera» consumen créditos. Su plan establece un límite máximo de clases y restricciones que puede utilizar.

Los tokens de los ejecutores de la granja de ejecutores, los secretos de los conectores y los emparejamientos permanecen en la aplicación web en https://runners.champrep.com. El CLI no puede acceder a ellos, independientemente de la clave que se utilice.

Ventana 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

Ventana 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

Ventana 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:

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

Declarar el CI como fallido en caso de que falle un control de calidad

Sección titulada «Declarar el CI como fallido en caso de que falle un control de calidad»

champrep qa gates status salidas 1 cuando falla el control de acceso, de modo que puede proteger cualquier paso del pipeline. En 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"

El mismo trabajo funciona en un GitLab .gitlab-ci.yml. Para realizar primero un análisis y después aplicar el control de acceso, facilite la clave qa:write y ejecute:

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

Un escaneo consume su asignación de control de calidad, por lo que muchos equipos realizan escaneos únicamente en la rama predeterminada y en las solicitudes de fusión, y aplican el control de acceso en el resto de casos.

Qué credencial. No utilice champrep auth login en CI. Cree una clave con API ámbito mientras está conectado a la CLI enCLI una sesión de navegador y guárdela como una variable de CI enmascarada y protegida denominada CHAMPREP_TOKEN. La CLI utiliza esa variable en lugar del llavero.

Ventana de terminal
champrep keys create --name "CI: acme/web" --scope code:read_api --scope qa:read --expires-in-days 90
Qué hace la tareaÁmbitos de aplicación
Lectura de código: proyectos, pipelines, registros de tareas, ejecutorescode:read_api
Modificar Code: ejecutar pipelines, reintentar trabajos, abrir y fusionar MR, actualizar runnerscode:api
Lea «Runner Farm» / «modificar grupos»runner_farm:read / runner_farm:write
Compruebe los controles de QA y los resultados / inicie análisis, active repositoriosqa:read / qa:write

Conceda únicamente lo que el trabajo requiera. Una clave no puede acceder a la administración de CodeCHAMPREP, a las credenciales de Runner Farm ni a nada que requiera su sesión web.

No hay indicaciones. Sin un terminal, cualquier comando que modifique algo se rechaza a menos que se le pase --yes (-y), y no se envía nada. Añada --yes en cada escritura de un script. champrep code clone nunca solicita información y no necesita --yes.

Salida legible por máquina. Añadir --json y analícelo con jq. El código de salida sigue siendo el mismo con --json. No analice el texto legible para los humanos.

Códigos de salida.

CódigoSignificadoAcción típica en la integración continua (CI)
0Éxito.Continúe.
1Fallo o denegación: una puerta de control fallida, un escaneo fallido, un proceso o una tarea seguida que no se ha completado con éxito, un clon que ha fallado, falta de acceso al elemento, no incluido en su plan, su rol, una decisión que requiere su sesión web o un archivo que falta --yes.El trabajo ha fallado; lea el mensaje.
3No ha iniciado sesión, o bien la clave no es válida o ha sido revocada.Corregir CHAMPREP_TOKEN.
4A la clave le falta un ámbito.Añada el ámbito a la clave.
5Límite de rate o capacidad.Vuelva a intentarlo más tarde.
6Fallo de red.Vuelva a intentarlo.
7Fallo de la pasarela o del servicio.Vuelva a intentarlo más tarde.
8pipelines wait Se ha agotado --timeout; el pipeline sigue en ejecución.Espere de nuevo o genere un --timeout.

Consulte la Referencia de comandos y API Claves para la automatización.