Como criar uma pipeline de CI/CD

Este guia irá te ensinar a configurar a pipeline de CI/CD do seu repositório integrando totalmente com a nossa infraestrutura.

Ao final de todos os passos, você terá uma pipeline que:

1. Faz deploy em produção quando há commit na main
2. Faz deploy em homologação quando há commit na develop
3. Realiza versionamento_semantico automaticamente
4. Executa testes automatizados

Este guia está dividido em partes. Nesta primeira parte, você vai configurar o deploy em produção.

1. Antes de começar, se seu projeto ainda não possui uma Dockerfile funcional, veja como_envelopar_meu_projeto_com_docker.
2. Se não conhece o Gitflow, vale a pena ver como é a nossa Padronização do Git.

Para implementar as pipelines do GitLab, é importante saber que ela funciona com Jobs organizados em Estágios, como uma linha de montagem.

Vamos apresentar brevemente esses conceitos pois, com a biblioteca TCE.Templates, não será necessário escrever os jobs na mão — apenas saber como eles funcionam.

Para mais informações, veja: CI/CD Jobs e CI/CD Pipelines.

Cada Job é um script (definido por nós, desenvolvedores) que realiza alguma tarefa: executar um teste, fazer o versionamento, realizar o deploy… Um exemplo de job de testes seria:

test-job:  # Nome do job, pode ser qualquer nome
  image: python:3.10-alpine
  stage: test
  before_script:

    - pip install pytest
  script:

    - pytest # Comando que efetivamente executa os tests
  allow_failure: false

  tags:
    - docker-pipes-runner  # Servidor onde ele será executado

• test-job — nome do Job.
• image: python:3.10-alpine — roda dentro de um container docker com essa imagem.
• stage: test — será executado durante o estágio de testes.
• script: pytest — o comando que executa os testes.
• before_script: pip install pytest — instala a dependência antes de rodar.
• allow_failure: false — se o pytest retornar erro, interrompe os próximos estágios.

Dica: O allow_failure: false funciona como um Quality Gate: previne que código com erros chegue à produção.

Se os Jobs são as tarefas, os Estágios são o cronograma da linha de montagem. Eles definem a ordem de execução: o estágio 2 só começa quando o estágio 1 terminar com sucesso. Jobs no mesmo estágio rodam em paralelo.

# A ordem aqui define a ordem de execução
stages:

  - lint                  # 1. Verifica estilo e erros de sintaxe
  - tests                 # 2. Executa os testes automatizados
  - sonar                 # 3. Analisa cobertura e segurança (Quality Gate)
  - semantic-release      # 4. Gera versão e Changelog se tudo acima passou
  - build                 # 5. Gera o pacote/imagem da nova versão
  - deploy                # 6. Publica no ambiente de destino

O GitLab centraliza a configuração da pipeline no arquivo .gitlab-ci.yml. Para editá-lo:

1. No menu lateral do seu projeto, acesse Compilação > Editor de pipeline.
2. Caso o arquivo ainda não exista, o GitLab oferecerá um modelo padrão. Apague o conteúdo inicial para começarmos do zero.

No topo do arquivo, declare o estágio de deploy que utilizaremos nesta etapa:

stages:

  - deploy

Mais estágios serão adicionados nas próximas partes do tutorial.

Para garantir simplicidade e padronização, não escrevemos scripts complexos em cada projeto. Em vez disso, importamos componentes pré-configurados da nossa biblioteca central, o TCE.Templates.

• No topo do Editor de Pipeline, clique em Catálogo de CI/CD > TCE.Templates. (Aqui é possível ver a documentação dos componentes)
• Localize o componente deploy-docker.
• Adicione o bloco de inclusão no seu arquivo:

stages:
  - deploy

include:
  - component: $CI_SERVER_FQDN/GER-TI/tce.kubernetes/tce.templates/deploy-docker@2.0.0  # Sempre especifique a versão
    inputs:
      environment: "production"
      compose-file: "docker-compose.yml"
      tag: dockers-prod-runner

O environment: “production” instrui o componente a realizar o deploy no ambiente de produção quando houver commit na branch main ou master.

O tag: dockers-prod-runner indica qual servidor irá receber o deploy. Para ver quais tags estão disponíveis veja https://gitsource.tce.go.gov.br/groups/GER-TI/-/runners. Para saber qual tag utilizar, veja gitlab_runners. Em nosso caso, como estamos fazendo deploy em produção, iremos colocar no servidor de produção vmdocker-01.tce.go.gov.br, e seu runner tem a tag dockers-prod-runner.

Os componentes funcionam como funções: você passa os parâmetros necessários (inputs) e a automação sabe como se comportar no seu projeto.

No final do component perceba que há um @2.0.0 que especifica qual versão da biblioteca utilizar.

É extremamente recomendado especificar qual versão da biblioteca você está utilizando, pois sua pipeline não terá chances de quebrar caso haja atualizações da biblioteca.

Na escrita deste artigo, a versão mais atual é a versão `2.0.0`. É recomendado sempre utilizar a versão mais recente.

Futuramente, caso haja alguma mudança na padronização, uma nova versão da TCE.Templates será lançada. Para atualizar a sua pipeline, bastará apenas atualizar para a nova versão. Extremamente Elegante.

Os runners são os servidores que executam os jobs da pipeline. Por padrão, runners de grupo não ficam habilitados automaticamente em projetos novos — é necessário ativá-los manualmente.

1. No menu lateral do projeto, acesse Configurações > CI/CD. 2. Expanda a seção Executores (Runners). 3. Na lista de Executores de grupo disponíveis, localize o runner com a tag dockers-prod-runner. 4. Clique no botão Habilitar ao lado dele.

Se pular este passo, a pipeline ficará travada com status “pending” e uma mensagem indicando que não há runners disponíveis para o job.

- Utilize a aba Visualizar no editor para garantir que a sintaxe está correta. - Se tudo estiver certo, clique em Commit changes no final da página. - Faça o commit direto na branch main.

Sua pipeline vai rodar imediatamente. Acesse Compilação > Pipelines para acompanhar a execução.

Após o commit na main, você deve ver: - Um pipeline criado automaticamente. - O estágio deploy sendo executado. - O job finalizando com sucesso (ícone verde ✓).

Se o job falhar, acesse o log do job clicando nele para investigar o erro.

• Parte 2: configurando_o_deploy_em_homologacao — adicionar deploy na branch develop com gitflow
• Parte 3: Adicionando o job de Semantic Release
• Parte 4: Adicionando o job de Testes