Encore CLI

O encore é uma ferramenta de linha de comando (CLI) projetada para automatizar e simplificar tarefas de desenvolvimento e manutenção em projetos da plataforma Integrado, especialmente aqueles hospedados no GitLab.

Com ele, você pode listar versões de pacotes, atualizar dependências em múltiplos projetos, modificar arquivos de forma massiva e configurar o acesso à API do GitLab.

Deployment

O fluxo de deployment é encapsulado no estágio deploy do .gitlab-ci.yml. A pipeline:

1. valida as variáveis obrigatórias (TAG, ENCORE_TOKEN, ENCORE_URL e a chave SSH GITLAB_SSH_PRIVATE_KEY),
2. constrói a imagem encore-deploy a partir do Dockerfile (que instala o Encore e o openssh-client),
3. executa o entrypoint.sh, que configura o SSH, define git config, carrega o token com encore config e chama encore update-projects.

O mesmo processo pode ser invocado manualmente com:

docker build -t encore-deploy .
docker run --rm \
  -e TAG="$TAG" \
  -e ENCORE_TOKEN="$ENCORE_TOKEN" \
  -e ENCORE_URL="$ENCORE_URL" \
  -e GITLAB_SSH_PRIVATE_KEY="$GITLAB_SSH_PRIVATE_KEY" \
  -e PACKAGE="${PACKAGE:-integrado-core}" \
  -e ONLY_FROM_VERSION="${ONLY_FROM_VERSION:-}" \
  encore-deploy

ONLY_FROM_VERSION é opcional e, quando presente, repassa --versions para o update-projects antes de clonar os repositórios.

Fluxo de Atualização de Projetos

flowchart TD
    A[Início do comando update-projects] --> B{Configurações válidas?}
    B -- Não --> Z[Solicitar encore config]
    B -- Sim --> C[Buscar projetos integrado-*]
    C --> D{Lista vazia?}
    D -- Sim --> Y[Encerrar sem alterações]
    D -- Não --> E[Iterar projetos]
    E --> F[Clonar repositório temporário]
    F --> G[Atualizar package.json]
    G --> H[Instalar dependências]
    H --> I{Alterações detectadas?}
    I -- Não --> J[Registrar ausência de mudanças]
    I -- Sim --> K[Commit e push]
    J --> L[Limpar arquivos temporários]
    K --> L
    L --> E
    E -. Próximo projeto .-> E
    L --> X[Fim]

Instalação

Para usar o Encore CLI, você precisa compilá-lo e executá-lo com o Node.js.

# A partir da raiz do projeto
npm install
npm run build
node src/dist/main.js <comando>

Para facilitar o uso, você pode criar um alias no seu terminal:

# Adicione ao seu .bashrc, .zshrc, etc.
alias encore="node /caminho/completo/para/encore/src/dist/main.js"

Comandos

A seguir estão os detalhes sobre cada comando disponível.

config

Configura as credenciais de acesso à API do GitLab, como o token pessoal e a URL da API. As informações são salvas localmente para serem usadas por outros comandos.

Como usar:

Ao executar o comando, você será solicitado a inserir seu token de acesso e a URL da API do GitLab.

encore config

list-versions

Verifica e lista as versões de um pacote NPM específico (integrado-core por padrão) em todos os projetos que começam com integrado- no GitLab.

Como usar:

encore list-versions [opções]

Opções:

| Opção | Descrição | |---------------|-------------------------------------------------------------------------| | --package | Nome do pacote NPM a ser verificado. | | --no-cached | Força a busca dos projetos diretamente do GitLab, ignorando o cache local. |

Exemplo:

Para listar as versões do pacote axios:

encore list-versions --package axios

update-projects

Atualiza a versão de um pacote no arquivo package.json de todos os projetos integrado-. O comando clona cada projeto, atualiza a versão, instala as dependências e envia um commit com a alteração.

Como usar:

encore update-projects

Opções:

| Opção | Descrição | |-------|-----------| | --package <valor> | Nome do pacote a ser atualizado. Padrão: integrado-core. | | --tag <valor> | Tag ou versão que será aplicada no package.json. Padrão: v2.10.0. | | --versions <valores...> | Lista de versões atuais (separadas por espaço ou vírgula) usada para filtrar os projetos que serão atualizados. Requer cache prévio de versões. | | --no-cached | Força a busca dos projetos diretamente no GitLab, ignorando o cache local. |

Exemplos:

# Atualiza todos os projetos integrado-* para a tag v2.11.0 do integrado-core
encore update-projects --package integrado-core --tag v2.11.0

# Atualiza somente projetos que atualmente usam as versões 2.8.5 ou 2.9.3
encore update-projects --versions 2.8.5 2.9.3 --tag v2.10.0

# Também é possível informar versões separadas por vírgula
encore update-projects --versions 2.8.5,2.9.3

💡 Para que o filtro de --versions funcione é necessário ter o arquivo output/versions.json populado (por exemplo, executando encore list-versions).

update-file

Encontra e substitui textos em um arquivo específico dentro de todos os projetos integrado-. É útil para fazer alterações em massa, como atualizar a versão de uma imagem em um Dockerfile.

Como usar:

encore update-file [opções]

Opções:

| Opção | Descrição | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | --filename <valor> | Nome do arquivo a ser modificado (ex: Dockerfile). | | --replacements <valor> | Expressão de busca e substituição no formato "original=>>novo". Pode ser usado várias vezes. A "original" é tratada como uma RegEx. | | --commit-message | Mensagem de commit personalizada para a alteração. | | --no-cached | Força a busca dos projetos diretamente do GitLab, ignorando o cache local. |

Exemplo:

Para atualizar a versão do Node.js em todos os Dockerfile dos projetos:

encore update-file \
  --filename Dockerfile \
  --replacements "FROM node:16=>>FROM node:18" \
  --commit-message "build: Atualiza versão base do Node.js para 18"

update-runner

Atualiza os runners atribuídos ("Assigned project runners") para todos os projetos integrado-, garantindo que passem a usar o runner informado.

Como usar:

encore update-runner [opções]

Opções:

| Opção | Descrição | |-------|-----------| | --runner-id <valor> | ID do runner que será atribuído aos projetos. | | --remove-runner-ids <valores...> | IDs de runners que devem ser removidos da atribuição (aceita valores separados por espaço ou vírgula). | | --no-cached | Força a busca dos projetos diretamente no GitLab, ignorando o cache local. |

Exemplo:

encore update-runner \
  --runner-id 12345 \
  --remove-runner-ids 54321 67890