Segredos no Bitbucket Pipelines com o Crunu e OIDC do passo

O que o Crunu faz no Bitbucket Pipelines

Um passo executa o seu comando por meio do crunu run. O agente crunu entra com um token de serviço, confere as assinaturas, descriptografa as variáveis em memória e inicia o comando com elas. Nada é gravado no disco.

crunu run --env web-app/staging -- npm test

O token recebe só os ambientes que você concede. Com um vínculo de CI (OIDC), ele só funciona junto com o token OIDC do passo, para o repositório, o branch e o ambiente de deployment que você definir. O próprio crunu lê o token do passo em BITBUCKET_STEP_OIDC_TOKEN.

Configuração

1. No Crunu, abra Service tokens e escolha New service token. Conceda os ambientes de que o passo precisa. O token só é mostrado uma vez.
2. No Bitbucket, adicione variáveis de repositório protegidas: CRUNU_TOKEN e CRUNU_SERVER, mais CRUNU_INSTALL_URL, CRUNU_INSTALL_SHA256, CRUNU_VERSION e CRUNU_BINARY_SHA256, do bloco CI setup da página do token. Na nuvem, CRUNU_SERVER é https://app.crunu.com.
3. Opcional: adicione um vínculo de CI (OIDC) na página do token. Escolha o provedor Bitbucket, o seu workspace e o repositoryUuid do repositório e, se precisar, branchName: main e o deploymentEnvironmentUuid do seu deployment de production.

Exemplo de pipeline

image: node:24

definitions:
  steps:
    - step: &test
        name: Tests with staging variables
        oidc:                 # only if the token has an OIDC rule
          audiences:
            - https://app.crunu.com   # your Crunu server as its own audience
        script:
          - curl -sSf "$CRUNU_INSTALL_URL" -o /tmp/crunu-install.sh
          - echo "$CRUNU_INSTALL_SHA256  /tmp/crunu-install.sh" | sha256sum -c -
          - sh /tmp/crunu-install.sh --version "$CRUNU_VERSION" --sha256 "$CRUNU_BINARY_SHA256" --user-install
          - crunu run --env web-app/staging -- npm test

pipelines:
  default:
    - step: *test

O passo instala uma versão fixa do crunu, confere o SHA-256 do instalador antes de executá-lo e roda o comando na própria imagem do passo, com todas as ferramentas dela.

Por que o audience importa

Defina como audience o endereço do seu servidor do Crunu, em oidc: audiences: do passo, como no exemplo. O audience padrão do workspace do Bitbucket também funciona, mas todos os serviços do workspace recebem um token com ele, então um audience dedicado é mais seguro. Um passo pode listar até 10 audiences. Os tokens do Bitbucket não trazem a claim jti, então o servidor do Crunu trata um segundo uso do mesmo token como reutilização e o recusa.

O pipe crunu

O produto também inclui um pipe do Bitbucket que reúne estes passos: ele instala o crunu, confere os dois checksums e executa o seu comando com crunu run. A imagem dele ainda não está publicada em nenhum registry, então, por enquanto, instale o crunu no passo como mostrado acima. Um passo que usa o pipe referencia a imagem pelo endereço:

        script:
          - pipe: docker://<registry>/<name>:<tag>
            variables:
              CRUNU_TOKEN: $CRUNU_TOKEN
              CRUNU_SERVER: $CRUNU_SERVER
              CRUNU_ENV: 'web-app/staging'
              CRUNU_VERSION: $CRUNU_VERSION
              CRUNU_INSTALL_URL: $CRUNU_INSTALL_URL
              CRUNU_INSTALL_SHA256: $CRUNU_INSTALL_SHA256
              CRUNU_BINARY_SHA256: $CRUNU_BINARY_SHA256
              COMMAND: 'npm ci && npm test'

Fixe a imagem numa tag de versão imutável ou num digest. O comando roda dentro do contêiner do pipe, que por padrão é baseado em Node.js 24, e não na imagem do passo. Com uma regra OIDC no token, adicione oidc: com o audience do seu servidor ao passo e OIDC: 'true' às variáveis do pipe. Sem essa flag, o pipe não repassa o token OIDC do passo nem ao crunu nem ao seu comando.

Mantenha o token fora de alcance

O comando sob o crunu run recebe apenas variáveis básicas, como PATH e HOME, mais as variáveis do ambiente, e nunca as credenciais do próprio crunu. As variáveis de repositório do Bitbucket continuam visíveis para todas as linhas de script fora do pipe e para todos os passos, então a proteção real é uma concessão estreita: dê a um token de CI o ambiente que ele monta e mantenha o production fora dele.

Revogação

Abra o token no Crunu e escolha Revoke. O próximo login dele é recusado, e um passo que já está rodando termina com o que recebeu. Se o token pode ter vazado, rotacione também as chaves dos ambientes que ele recebeu e reemita os valores contidos neles nos respectivos provedores.

Veja também

• CI/CD no Crunu
• Bitbucket Pipelines na documentação
• Vincule um token com OIDC
• Tokens de serviço