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.
Faça login e escolha uma conta
Seção intitulada “Faça login e escolha uma conta”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 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:
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 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.
CHAMPREP Code
Seção intitulada “CHAMPREP Code”
Encontre um projeto e seu endereço de clonagem
Seção intitulada “Encontre um projeto e seu endereço de clonagem”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)"Variante de script:
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
Configurar credenciais do git
Seção intitulada “Configurar credenciais do git”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.
- Abrir
https://code.champrep.com/-/settings/ssh_keys. - Cole sua chave pública, por exemplo, o conteúdo de
~/.ssh/id_ed25519.pub. - Verifique a chave e a conexão:
champrep code ssh-keys lsgit ls-remote git@code.champrep.com:acme/web.git HEADHTTPS com um token de acesso pessoal.
- Abrir
https://code.champrep.com/-/settings/tokens. - Crie um token com o escopo
read_repository, ouwrite_repositoryse o senhor fizer um push. Defina uma data de validade. - Deixe que o armazenamento de credenciais do git mantenha o token no seu keychain do sistema:
# 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 libsecretNo 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:
git clone https://code.champrep.com/acme/web.gitA 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.
Clonar todos os meus projetos
Seção intitulada “Clonar todos os meus projetos”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.
champrep code clone --membership --dest ~/src --sshOutras opções:
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 projectsConsulte o plano primeiro. Uma simulação lista cada projeto e o que aconteceria, sem alterar nada:
champrep code clone --membership --dest ~/src --dry-run
Clone um grupo, com seus subgrupos
Seção intitulada “Clone um grupo, com seus subgrupos”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 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.
Mantenha um espelho local atualizado
Seção intitulada “Mantenha um espelho local atualizado”Execute o mesmo comando novamente com --update. Ele clona novos projetos e atualiza os que você já possui:
champrep code clone --group acme --include-subgroups --dest ~/src --ssh --updatePara 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:
# 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>&1Variante de script, listando o que falhou:
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:
- Carregue sua chave em
ssh-agent(ssh-add). - 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”champrep code pipelines ls acme/web --limit 10champrep code pipelines ls acme/web --ref main --limit 1champrep code pipelines ls acme/web --status failedVariante de script: exibir o status do pipeline mais recente em main:
champrep code pipelines ls acme/web --ref main --limit 1 --json | jq -r '.[0] | "\(.id) \(.status)"'
Aguarde um pipeline
Seção intitulada “Aguarde um pipeline”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:
git pushchamprep 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.
champrep code pipelines wait acme/web --ref main # the newest pipeline on main nowchamprep code pipelines wait acme/web 9921 --timeout 30m # one pipelineExecute um pipeline e aguarde esse específico:
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:
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:
champrep code jobs log acme/web 4182 --follow
Repita ou cancele um pipeline
Seção intitulada “Repita ou cancele um pipeline”champrep code pipelines retry acme/web 9921 --yes # reruns the failed and canceled jobschamprep 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”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 jobVariante de script, imprimindo as últimas 30 linhas de cada tarefa com falha em um 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 30done
Abra uma solicitação de mesclagem e mescle-a
Seção intitulada “Abra uma solicitação de mesclagem e mescle-a”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 succeedsVariante de script, capturando o número da nova solicitação de mesclagem:
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 --yesO 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”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 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:
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).
Registrar um executor
Seção intitulada “Registrar um executor”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.
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.24Usar --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.
Fazenda de Executores
Seção intitulada “Fazenda de Executores”
Verificar uso e créditos
Seção intitulada “Verificar uso e créditos”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" }
Veja os pools e o que está em espera
Seção intitulada “Veja os pools e o que está em espera”champrep rf connections lschamprep rf pools lschamprep rf pools show pol_01HZX9K4champrep rf jobs ls --state waiting,heldVariante de script, mostrando o nível de ocupação de cada pool:
champrep rf pools ls --json | jq -r '.pools[] | "\(.id) \(.state) \(.busy)/\(.max_concurrent)"'
Dimensionar um pool
Seção intitulada “Dimensionar um 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 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.
CHAMPREP QA
Seção intitulada “CHAMPREP QA”
Ativar um repositório
Seção intitulada “Ativar um repositório”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" --yes
Executar a varredura e aguardar o resultado
Seção intitulada “Executar a varredura e aguardar o resultado”champrep qa scan "$REPO" --ref main --watch --yes # exits 1 when the scan or its gate failschamprep qa scans ls --repo "$REPO" --limit 5
Listar descobertas de alta gravidade
Seção intitulada “Listar descobertas de alta gravidade”champrep qa findings ls --repo "$REPO" --severity critical,highchamprep qa findings ls --severity high --type secret # leaked secrets, whole workspacechamprep qa findings show QA-0970Variante de script:
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 --yesUma 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.
Usando o CLI na CI e em scripts
Seção intitulada “Usando o CLI na CI e em scripts”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.
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, executores | code:read_api |
| Alterar o Code: executar pipelines, repetir tarefas, abrir e mesclar MRs, atualizar runners | code:api |
| Leia sobre o Runner Farm / altere os pools | runner_farm:read / runner_farm:write |
| Verifique os controles de QA e as descobertas / inicie varreduras, ative repositórios | qa: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ódigo | Significado | Ação típica na CI |
|---|---|---|
0 | Sucesso. | Continue. |
1 | Falha 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. |
3 | Não está conectado, ou a chave é inválida ou foi revogada. | Corrigir CHAMPREP_TOKEN. |
4 | Falta um escopo à chave. | Adicione o escopo à chave. |
5 | Limite de taxa ou capacidade. | Tente novamente mais tarde. |
6 | Falha de rede. | Tente novamente. |
7 | Falha no Gateway ou no serviço. | Tente novamente mais tarde. |
8 | pipelines 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.