20 min para completar
Guia rápido para GitLab Continuous Integration
Bem-vindo ao guia rápido do GitLab CI, onde você será guiado através do processo de configurar um projeto no GitLab e criar uma configuração CI simples no código. Este guia permitirá que você inicie rapidamente sua jornada com o GitLab CI.
As seguintes tarefas serão apresentadas neste guia rápido:
- Criar um novo projeto.
- Elaborar sua configuração inicial de CI/CD e executar o pipeline.
- Acessar e revisar os resultados da execução.
- Introduzir condições baseadas em regras para determinar execuções de jobs.
- Aproveitar o poder dos Pipeline Templates para integração perfeita de configurações benéficas.
Antes de começar
Certifique-se de ter uma conta GitLab. Se você não tem, cadastre-se aqui.
Dentro de um projeto, vários componentes como seu código, configuração de CI, planejamento, análises e membros da equipe são gerenciados. Neste guia, criaremos um novo projeto em branco, contendo apenas um arquivo readme.
- Crie um novo projeto clicando no ícone de mais no lado direito da barra superior e selecionando Novo projeto/repositório
- Selecione Criar projeto em branco. Em
Nome do projetodigite my-project. - Clique em Criar projeto.
- Parabéns! Você criou com sucesso seu primeiro projeto.
No GitLab, a configuração de CI é definida em código usando sintaxe YAML. Esta configuração especifica instruções para a máquina runner sobre execução de jobs, ordem dos jobs, condições dos jobs e muito mais. Para definir a configuração de CI, você precisa criar um arquivo chamado .gitlab-ci.yml, que deve estar localizado na raiz do seu repositório. Neste guia, utilizaremos o Web IDE para criar e editar este arquivo.
Para acessar o Web IDE, simplesmente clique no botão rápido Web IDE localizado no seu projeto. Uma vez dentro do Web IDE, navegue até o explorador de arquivos no lado esquerdo. Clique com o botão direito dentro do explorador de arquivos e escolha a opção Novo Arquivo. Nomeie o arquivo recém-criado como .gitlab-ci.yml.
A ordem de execução dos jobs é determinada pelos estágios definidos na configuração. Neste guia, definiremos três estágios: build, test e package, nesta ordem específica. Copie e cole o seguinte código no arquivo .gitlab-ci.yml:
stages:
- build
- test
- package
Imagine um cenário onde você precisa criar dois arquivos de texto. É de extrema importância que a concatenação desses arquivos inclua a frase "Hello world." Nosso objetivo é construir, testar e empacotar este requisito utilizando jobs de pipeline.
Especificaremos um job de build que realiza as seguintes tarefas: criar um arquivo de texto com a palavra "Hello,", criar outro arquivo de texto com a palavra "World," e gerar um terceiro arquivo que armazena o conteúdo combinado dos dois arquivos. Salvaremos o terceiro arquivo como um artefato, para que jobs subsequentes nos estágios de test e package possam acessá-lo. Insira o código fornecido abaixo do bloco stages:
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
Para validar a integridade do nosso build, incorporaremos um job de teste. Este job examinará se o arquivo compiled.txt realmente contém a frase esperada "Hello world". Insira o seguinte código abaixo do job de build:
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world '
Após a conclusão bem-sucedida do teste, nosso próximo objetivo é gerar um pacote para nosso código. Para conseguir isso, incluiremos um job de empacotamento. É importante notar que se o teste falhar, todo o pipeline será considerado mal-sucedido e não prosseguirá. Insira o código fornecido abaixo do job de teste:
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
stages: # Lista de estágios para jobs e sua ordem de execução
- build
- test
- package
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
Aqui está um link para o arquivo de configuração em nosso projeto de exemplo.
Parabéns!! Você construiu seu primeiro pipeline de CI.
Para ativar a integração contínua (CI) dentro do nosso projeto, devemos fazer push do arquivo .gitlab-ci.yml para o repositório. Uma vez que este arquivo esteja localizado na raiz do repositório, cada commit feito no projeto iniciará automaticamente um pipeline de CI. O pipeline inicial começará imediatamente após fazer push deste arquivo para o servidor.
- Clique no ícone Merge localizado à esquerda do explorador de arquivos.
- Forneça uma mensagem de commit como "Adicionando configuração de CI."
- Clique em Commit & Push.
- Quando perguntado "Fazer commit em um novo branch?" selecione "Não, usar o branch atual main".
- Para retornar ao seu projeto, clique no botão Ir para o projeto situado no lado inferior esquerdo.
Parabéns! Seu projeto agora está configurado com sucesso para iniciar automaticamente um pipeline de CI para cada commit de código.
Enquanto o pipeline está executando, você pode monitorar seu status na aba CI/CD. Este recurso permite que você acompanhe facilmente o progresso dos seus jobs, incluindo seu status de execução (como se eles iniciaram, passaram, falharam, etc.), bem como qualquer saída gerada pelos seus scripts de job.
- Navegue até o projeto GitLab e localize o menu à esquerda.
- Clique em CI/CD no menu, clique em Pipelines.
- Na página Pipelines, localize o botão do pipeline na coluna Status. Clique nele para abrir o gráfico do pipeline.
- Agora, você pode observar os jobs e seus respectivos status dentro do gráfico do pipeline.
- Para explorar um job específico, clique nele para abrir o console do job. Este console exibe todos os passos executados na máquina Runner.
- Abra o console do job package para ver os passos que foram processados pelo runner.
- O job package gera um artefato, você pode baixá-lo clicando no botão download localizado no lado direito.
- Seguindo estes passos, você pode acompanhar efetivamente o status do pipeline, inspecionar detalhes dos jobs e recuperar quaisquer artefatos ou pacotes relevantes produzidos durante a execução do pipeline.
Parabéns por executar com sucesso seu primeiro pipeline. O pipeline foi bem-sucedido! Você agora visualizou os resultados e baixou o artefato do job.
Vamos alterar o valor esperado no job de teste, o job de teste falhará assim como todo o pipeline falhará.
- Edite o job test modificando a frase "Hello World" para "hello world" (com letras minúsculas).
- Faça commit das mudanças no código e proceda para visualizar o pipeline, similar ao Passo 4.
- Ao inspecionar o pipeline, você observará que o job de teste falhou. Além disso, o job package subsequente não iniciou, e o pipeline em si falhou como esperado.
No passo 5 vimos que a falha do job fez todo o pipeline falhar. Você pode introduzir lógica no seu pipeline que determina quando uma falha de job causará a falha de todo o pipeline com os seguintes passos:
- Avalie as condições sob as quais você quer que uma falha de job resulte em falha do pipeline. Por exemplo, você pode querer forçar a falha do pipeline se um job falhar no branch main ou padrão, enquanto permite que falhas de jobs em outros branches prossigam com o pipeline.
- Defina regras que governam o comportamento de falha. Você pode aproveitar variáveis como $CI_COMMIT_BRANCH para verificar o branch atual e tomar decisões baseadas nele.
- Configure as condições apropriadas e especifique se o job deve ser marcado como allow_failure: false ou allow_failure: true.
- Adicione condições rules/if ao seu job de teste.
- Use a palavra-chave allow_failure definida como true ou false baseada no branch.
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
allow_failure: false
- if: $CI_COMMIT_BRANCH
allow_failure: true
Para simplificar a configuração do pipeline, você pode aproveitar os templates de pipeline integrados fornecidos pelo GitLab. Estes templates oferecem configurações pré-definidas para casos de uso comuns, como verificações de segurança, deployments AWS, etc.
Siga estes passos para utilizar os templates de pipeline integrados:
- Explore os templates de pipeline disponíveis oferecidos pelo GitLab para vários cenários como build, teste, deploy e muito mais. Estes templates podem ser encontrados aqui.
- Selecione o template que se alinha com seus requisitos.
- Incorpore o template na sua configuração de pipeline referenciando-o no seu arquivo .gitlab-ci.yml. Você pode tipicamente fazer isso importando o template usando a palavra-chave include e especificando o caminho ou URL para o arquivo do template.
Neste guia adicionaremos uma verificação de Code Quality à nossa configuração usando o template Code-Quality.
Inclua o template de qualidade de código no seu .gitlab-ci.yml adicionando este código abaixo do bloco stages.
include:
- template: Jobs/Code-Quality.gitlab-ci.yml
Faça commit e push desta mudança.
Você notará que um job Code quality foi adicionado ao seu pipeline. O scanner Code Quality analisará minuciosamente quaisquer mudanças de código commitadas neste repositório e fornecerá feedback valioso, destacando quaisquer problemas de qualidade de código que requerem atenção e melhoria. Esta percepção valiosa permite que você melhore a qualidade geral do seu código e otimize seu desempenho.
É isso! Com estes passos, você deve conseguir começar com GitLab CI e automatizar os processos de build e teste do seu projeto.
