Pular para o conteúdo
Documentation

Tarefas comuns para Code, Runner Farm e QA

Esta página é um conjunto de receitas curtas. Cada uma resolve uma única tarefa com comandos que você pode copiar. Quando um script for útil, haverá uma --json | jq variante. Para cada opção de um comando, consulte as páginas de referência: CHAMPREP Código, Runner Farm e CHAMPREP QA.

Nos exemplos, acme é um grupo, acme/web é um projeto, e code.champrep.com é o CodeCHAMPREP.

Terminal window
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 O Code não possui uma opção para alternar entre espaços de trabalho. Um projeto pertence a um grupo ou ao seu namespace pessoal, e sua função nele determina o que você pode fazer.

A Runner Farm e o QA atuam em um espaço de trabalho: sua conta pessoal, uma organização ou uma equipe. Liste aqueles que você pode utilizar e, em seguida, passe o KEY coluna de rf accounts ls (personal, organization:<id> ou team:<id>) com --workspace:

Terminal window
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 define o padrão para comandos de organização, como business members. O Runner Farm e o QA ignoram isso. Passe --workspace para eles, ou deixe que o serviço escolha o espaço de trabalho da mesma forma que o aplicativo web faz.

Terminal window
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:

Terminal window
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

O `git` se comunica diretamente com o `CHAMPREPCode`, e não por meio do `CLI,` portanto, ele precisa de sua própria credencial. O `CHAMPREPCode` não aceita seu CLI login como senha do `git`. Criar um token de acesso pessoal ou adicionar uma chave SSH constitui uma alteração de credencial, portanto, é necessária sua sessão da web com login ativo. Faça isso uma vez no navegador.

SSH (recomendado). Isso funciona para todos os projetos, e nada é armazenado em texto simples.

  1. Abrir https://code.champrep.com/-/settings/ssh_keys.
  2. Cole sua chave pública, por exemplo, o conteúdo de ~/.ssh/id_ed25519.pub.
  3. Verifique a chave e a conexão:
Terminal window
champrep code ssh-keys ls
git ls-remote git@code.champrep.com:acme/web.git HEAD

HTTPS com um token de acesso pessoal.

  1. Abrir https://code.champrep.com/-/settings/tokens.
  2. Crie um token com o escopo read_repository, ou write_repository se o senhor fizer um push. Defina uma data de validade.
  3. Deixe que o armazenamento de credenciais do git mantenha o token no seu keychain do sistema:
Terminal window
# 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

No Linux, o libsecret O helper só funciona quando o git-credential-libsecret O programa está instalado. Muitas distribuições não o instalam junto com o git. Instale-o a partir dos pacotes da sua distribuição ou compile-o a partir do git’s contrib/credential/libsecret pasta. Verifique com command -v git-credential-libsecret. Sem um chaveiro, evite o store utilitário, que grava o token em ~/.git-credentials em texto simples. Use cache --timeout=3600 em vez disso, que o mantém apenas na memória, ou use SSH.

Em seguida, clone um projeto manualmente. O git solicita um nome de usuário (qualquer valor serve) e uma senha (cole o token), e o armazenamento de credenciais os mantém:

Terminal window
git clone https://code.champrep.com/acme/web.git

A partir de então, o git e champrep code clone utilize o token armazenado. Nunca coloque um token em uma URL remota, como https://user:TOKEN@…: o git grava a URL em .git/config, e qualquer pessoa que ler esse arquivo ou seu histórico do shell poderá usá-lo . champrep code clone recusa endereços de clonagem que contenham uma credencial.

Clone todos os projetos dos quais o(a) senhor(a) é membro, diretamente ou por meio de um grupo, para ~/src. Cada projeto é armazenado em seu próprio namespace, por exemplo ~/src/acme/platform/api.

Terminal window
champrep code clone --membership --dest ~/src --ssh

Outras opções:

Terminal window
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 o plano primeiro. Uma simulação lista cada projeto e o que aconteceria, sem alterar nada:

Terminal window
champrep code clone --membership --dest ~/src --dry-run

Terminal window
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 define quantas clonagens são executadas simultaneamente (padrão 4, no máximo 16). Projetos arquivados são excluídos, a menos que o senhor adicione --archived. --search TEXT mantém apenas projetos cujo nome ou caminho contenha o texto.

Execute o mesmo comando novamente com --update. Ele clona novos projetos e atualiza os que você já possui:

Terminal window
champrep code clone --group acme --include-subgroups --dest ~/src --ssh --update

Para cada clone existente, --update primeiro verifica se o seu origin é o projeto, por meio de seu endereço HTTPS ou SSH. Uma cópia de outro repositório nesse caminho é relatada como mismatch (falha) e é deixado de lado. Em seguida, ele é executado git fetch --prune e uma mesclagem apenas em fast-forward do ramo atual. O trabalho local nunca é sobrescrito:

  • um branch que tenha divergido é relatado como falho, e o senhor deve mesclá-lo ou rebaseá-lo por conta própria;
  • Um HEAD desanexado ou um ramo sem um upstream é buscado apenas e relatado como no-upstream.

Sem --update, os clones existentes são ignorados.

O comando é encerrado com um resumo e sai 1 Quando algum projeto falhar, uma tarefa agendada poderá alertá-lo:

Terminal window
# 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, listando o que falhou:

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

Os status em JSON são cloned, updated, up_to_date, no_upstream, skipped, failed (com "reason": "mismatch" (para clonar outro repositório), interrupted e not_started após pressionar Ctrl-C e, com --dry-run, would_clone, would_update e would_skip.

champrep code clone nunca solicita confirmação, pois várias clonagens são executadas simultaneamente. O git é executado com GIT_TERMINAL_PROMPT=0. O SSH é executado com BatchMode=yes, portanto, ele não solicita senha, frase secreta ou chave do host, a menos que o senhor defina as suas próprias GIT_SSH_COMMAND ou core.sshCommand. Antes de uma clonagem em massa via SSH, faça duas coisas:

  1. Carregue sua chave em ssh-agent (ssh-add).
  2. Conecte-se manualmente uma vez para aceitar a chave do host (git ls-remote git@code.champrep.com:acme/web.git HEAD).

Um projeto que não dispõe de credenciais para o Git falha ao utilizar could not read Username via HTTPS ou Permission denied (publickey) via SSH. Configure as credenciais acima e execute o comando novamente.

Ctrl-C interrompe a execução de forma limpa. Nenhum novo clonagem é iniciada, as que estão em andamento são interrompidas (o git remove uma clonagem pela metade) e o resumo mostra o que foi feito. Execute o comando novamente para continuar: as clonagens concluídas são ignoradas.

Apenas https:// e os endereços SSH no host do CodeCHAMPREP são clonados, e o git é executado com todos os outros meios de transporte desativados.

Liste os pipelines e verifique o mais recente em um branch

Seção intitulada “Liste os pipelines e verifique o mais recente em um branch”
Terminal window
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: exibir o status do pipeline mais recente em main:

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

pipelines wait aguarda até que um pipeline seja concluído, e seu código de saída é o resultado: 0 sucesso; 1 falhou, foi cancelado, ignorado ou interrompido em uma tarefa manual ; 8 ainda em execução quando --timeout (padrão 60m) se esgotou.

Após um push, aguarde o pipeline do commit que o senhor enviou:

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

--sha aguarda que o Code crie o pipeline desse commit e, em seguida, que ele seja concluído. --sha HEAD Também funciona dentro do repositório. Evite --ref main logo após um push. Ele utiliza o pipeline mais recente no branch naquele momento, que ainda pode ser o pipeline do commit anterior se o Code ainda não tiver criado o correspondente ao seu push, e o senhor acabaria fazendo a implantação com o resultado incorreto.

Terminal window
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

Execute um pipeline e aguarde esse específico:

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

O progresso e a linha de status final são direcionados para o stderr. Com --json, o stdout contém o pipeline concluído, e o código de saída permanece o mesmo:

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

Um pipeline que chega a uma tarefa manual, como uma implantação iniciada manualmente, fica parado nesse ponto até que uma pessoa intervenha. pipelines wait saídas 1 com uma mensagem informando isso. Inicie o trabalho com champrep code jobs play, ou passar --manual-ok para considerar o pipeline concluído (sair 0). Uma tarefa agendada (adiada) inicia automaticamente, portanto a espera continua durante a execução.

Para acompanhar um trabalho, siga seu log. O comando retorna quando o trabalho for concluído e encerrado 1 quando a tarefa falhou ou foi cancelada:

Terminal window
champrep code jobs log acme/web 4182 --follow

Terminal window
champrep code pipelines retry acme/web 9921 --yes # reruns the failed and canceled jobs
champrep code pipelines cancel acme/web 9921 --yes

Leia o log de um trabalho com falha, acompanhe um trabalho em execução, reexecute um trabalho

Seção intitulada “Leia o log de um trabalho com falha, acompanhe um trabalho em execução, reexecute um trabalho”
Terminal window
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, imprimindo as últimas 30 linhas de cada tarefa com falha em um pipeline:

Terminal window
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

Terminal window
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 o número da nova solicitação de mesclagem:

Terminal window
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

O que requer o aplicativo web. Fusão ou aprovação em um ramo protegido Essa é uma decisão que somente o(a) senhor(a) pode tomar, estando conectado(a) ao CodeCHAMPREP no navegador. O CLI então é interrompido com needs your web session … (SESSION_REQUIRED) e código de saída 1. Fazer login na CLI novamenteCLI não altera isso. Abra a solicitação de mesclagem no navegador e faça a mesclagem ou a aprovação por lá. Ramos desprotegidos funcionam na CLICLI.

Executores: listar, ver quem está online, marcar, pausar e retomar

Seção intitulada “Executores: listar, ver quem está online, marcar, pausar e retomar”
Terminal window
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 e --remove-tag ler as tags do executor e gravar a lista completa de volta. Se alguém alterar as tags entre essas duas etapas, a alteração será perdida; portanto, verifique com runners show quando várias pessoas gerenciam um executor.

Variante de script, pausando todos os executores com uma tag antes da manutenção:

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

É necessário ter o papel de Mantenedor para visualizar e alterar os executores de um projeto, e o de Proprietário para os executores de um grupo. Os executores de instância destinam-se aos administradores de instância (runners ls --all).

Crie um executador de projeto ou de grupo a partir do CLI e conecte uma máquina a ele com champrep-code-runner. O token (ccrt_…) é impresso uma vez, na saída padrão , e nunca é registrado. Sua criação sempre requer --yes.

Terminal window
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

Usar --group acme em vez de --project para um executador de grupo (é necessário ter permissão de Proprietário). Adicionar --no-untagged para selecionar apenas tarefas marcadas, e --protected para executar apenas ramificações e tags protegidas. Você também pode criar o executor no aplicativo web, em Configurações > CI/CD > Executores do projeto ou grupo. Consulte registrar um executor.

A CLI não pode redefinir o token de um executador nem criar executadores de instância. Realize ambas as ações no aplicativo web.

Terminal window
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" }

Terminal window
champrep rf connections ls
champrep rf pools ls
champrep rf pools show pol_01HZX9K4
champrep rf jobs ls --state waiting,held

Variante de script, mostrando o nível de ocupação de cada pool:

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

Terminal window
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 mantém os executores aquecidos prontos, para que as tarefas iniciem mais rapidamente, mas os executores aquecidos consomem créditos. Seu plano estabelece limites para as classes e restrições que você pode utilizar.

Os tokens dos executores da Farm de Executores, os segredos dos conectores e os emparelhamentos permanecem no aplicativo web em https://runners.champrep.com. O CLI não consegue acessá-los, independentemente da chave utilizada.

Terminal window
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

Terminal window
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

Terminal window
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:

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

Reprovar a CI em caso de falha no controle de qualidade

Seção intitulada “Reprovar a CI em caso de falha no controle de qualidade”

champrep qa gates status encerra 1 quando o gate falha, para que possa proteger qualquer etapa do pipeline. No 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"

A mesma tarefa funciona em um GitLab .gitlab-ci.yml. Para fazer a verificação primeiro e, em seguida, aplicar o controle de acesso, forneça a chave qa:write e execute:

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

Uma verificação utiliza sua cota de QA; por isso, muitas equipes realizam a verificação apenas no branch padrão e nas solicitações de mesclagem, e aplicam o gate em todos os outros casos.

Qual credencial. Não utilize champrep auth login na CI. Crie uma chave com API escopo enquanto estiver conectado à CLI em uma sessão do navegador e armazene-a como uma variável de CI mascarada e protegida chamada CHAMPREP_TOKEN. O CLI utiliza essa variável em vez do chaveiro.

Terminal window
champrep keys create --name "CI: acme/web" --scope code:read_api --scope qa:read --expires-in-days 90
O que a tarefa fazÂmbitos
Leitura de código: projetos, pipelines, logs de tarefas, executorescode:read_api
Alterar o Code: executar pipelines, repetir tarefas, abrir e mesclar MRs, atualizar runnerscode:api
Leia sobre o Runner Farm / altere os poolsrunner_farm:read / runner_farm:write
Verifique os controles de QA e as descobertas / inicie varreduras, ative repositóriosqa:read / qa:write

Conceda apenas o que a tarefa necessita. Uma chave não pode acessar a administração do CodeCHAMPREP, as credenciais da Runner Farm ou qualquer recurso que exija sua sessão na web.

Sem solicitações. Sem um terminal, qualquer comando que altere algo será recusado, a menos que o senhor passe --yes (-y), e nada é enviado. Adicione --yes para cada gravação em um script. champrep code clone nunca solicita nada e não requer --yes.

Saída legível por máquina. Adicionar --json e analise-o com jq. O código de saída permanece o mesmo com --json. Não analise o texto legível por humanos.

Códigos de saída.

CódigoSignificadoAção típica na CI
0Sucesso.Continue.
1Falha ou recusa: um gate com falha, uma varredura com falha, um pipeline ou tarefa acompanhada que não foi bem-sucedida, um clone com falha, falta de acesso ao item, item fora do seu plano, sua função, uma decisão que requer sua sessão na web ou um arquivo ausente --yes.Rejeite o trabalho; leia a mensagem.
3Não está conectado, ou a chave é inválida ou foi revogada.Corrigir CHAMPREP_TOKEN.
4Falta um escopo à chave.Adicione o escopo à chave.
5Limite de taxa ou capacidade.Tente novamente mais tarde.
6Falha de rede.Tente novamente.
7Falha no Gateway ou no serviço.Tente novamente mais tarde.
8pipelines wait esgotou --timeout; o pipeline ainda está em execução.Aguarde novamente ou gere --timeout.

Consulte o referência de comandos e API chaves para automação.