Repositório com o exemplo de CI/CD apresentado na palestra code no code: Linha Protheus - Jornada CI/CD Protheus no Universo TOTVS 2024.
Para baixá-lo, faça um clone deste repositório em seu ambiente local: git clone https://github.com/totvs/protheus-ci-universo.
Dúvidas podem ser encaminhadas via issue neste repositório. Sugestões via Pull Requests.
Se deseja subir o ambiente Protheus via Docker deste exemplo veja o tópico Ambiente Protheus com Docker.
Esta pipeline de exemplo consiste em 4 etapas (veja aba Actions deste repositório):
on push
├── 1. Code Analysis (inspeção - CI) -> Realiza a execução da análise de qualidade de código;
├── 2. Build (construção - CI) -> Compila os fontes e gera o RPO Custom;
├── 3. TIR (teste - CD*/CI) -> Baixa o RPO custom e realiza os testes usando o TIR sem interface;
└── 4. Patch Gen (artefato final - CD) -> Gera um patch com os fontes Protheus do repositório.
Esta pipeline foi configurada para executar sequencialmente, cada uma das etapas depende que a anterior tenha sido executada com sucesso para continuar.
A definição está no arquivo .github/workflows/pipeline.yml, onde cada etapa é um job do GitHub Actions que executa alguns scripts para realizar a tarefa da etapa em questão.
* Como explicamos na apresentação, o TIR depende de um ambiente Protheus em execução para funcionar, logo precisamos subir um ambiente de teste com o RPO atualizado, neste ponto fazemos uma espécie de CD para subir um ambiente local em Docker.
Conforme explicado no tópico Ambiente Protheus com Docker, para subir o ambiente com essas imagens Docker de desenvolvimento e base iniciada, é necessário passar como volume os RPOs, includes, dicionários e INIs.
Como alguns artefatos são privados e não podemos disponibilizar publicamente (como RPO e dicionários), deixamos esses arquivos num servidor privado e na pipeline apenas fazemos o download deles na hora de subir a base Protheus.
Você pode seguir o mesmo conceito (usando um servidor HTTP ou repositório privado) para baixar os artefatos na pipeline ou criar uma imagem customizada já contendo os artefatos embarcados, veja o tópico: Herdando imagem base.
Uma outra solução seria executar um agent on promise (hospedado em sua infraestrutura) dos runners do GitHub (veja aqui a documentação sobre isso) conectado a uma instância Docker para execução dos jobs da pipeline. Dessa forma os artefatos ainda estariam seguros e poderiam ser passados por volume para o runner e container protheus.
Para tratar os erros e falhas dos scripts de testes do TIR, é necessário que o script da suíte tenha um tratamento para quebrar em caso de falhas. Para isso adicione a seguinte instrução no final da suíte:
runner = unittest.TextTestRunner(verbosity=2)
result = runner.run(suite)
if len(result.errors) > 0 or len(result.failures) > 0:
print("custom exit")
exit(1)Na imagem* abaixo é possível ver uma execução com sucesso da pipeline, onde foram executadas as 4 etapas e gerado os artefatos (custom rpo e patch) para aplicação no ambiente.
* Imagem anexada pois a retenção máxima do GitHub Actions é de 90 dias.
As imagens Docker de desenvolvimento que fornecemos contém apenas os arquivos binários (ex.: AppServer e DBAccess), portanto os outros artefatos como RPO, dicionário e INI devem ser passados por volume.
Se deseja subir o ambiente Protheus via Docker deste exemplo (que usamos para executar os testes do TIR), siga os seguintes passos:
- Baixe os seguintes artefatos: includes (apenas para compilações), rpo default e o dicionário;
- Adicione na pasta protheus os artefatos baixados em suas respectivas subpastas (essas subpastas são volumes no compose que sobe o ambiente:
./ci/docker/docker-compose.yml); - Execute o script:
cd protheus-ci-universo && bash ci/scripts/up_env.shpara iniciar o compose do ambiente; - Configure os dados do ambiente (ip/porta webapp) nas configs do TIR (
tir/config.json) caso tenha alterado o INI.
Após isso o ambiente pode ser acessado via webapp: http://localhost:8080.
O banco de dados é uma imagem PostgreSQL já com a estrutura de dicionário iniciada (empresa 99).
Caso deseje você também pode criar uma nova imagem (Dockerfile) adicionando os artefatos (RPO e/ou dicionário) e herdando (FROM) as nossas imagens como base para não precisar volumar os arquivos.
Porém não recomendados essa prática para o custom.rpo por exemplo, pois dessa forma cada vez que o container for encerrado, tudo que foi compilado será perdido.
Estes são os scripts extras desta pipeline de exemplo:
up_env.sh: Sobe a stack ambiente Protheus local em Docker;down_env.sh: Remove a stack do ambiente Protheus;list-files.sh: Lista os arquivos de código fonte Protheus para geração do patch;
Este projeto contém a seguinte estrutura de pastas e seus respectivos propósitos:
.
├── .github
│ └── workflows
│ └── pipeline.yml (pipeline GitHub Actions)
├── analyser (arquivos do analisador estático)
│ ├── config.json (arquivo de configuração do analisador)
│ └── output (saída da execução da análise)
├── ci
│ ├── scripts (scripts externos da pipeline)
│ └── docker (arquivos para execução do ambiente Protheus local)
├── protheus (arquivos para execução local do Protheus e AppServer command line via Docker)
│ ├── apo (volume dos RPOs do ambiente Protheus)
│ ├── includes (volume dos includes da compilação)
│ └── systemload (volume dos arquivos de dicionário)
├── src (códigos-fonte)
└── tir (suítes de testes e configuração para execução do TIR)