Como Configurar Pipelines de Integração Contínua (CI) do GitLab no Ubuntu 20.04

Todo desenvolvedor entende quão crucial é o controle de versão para o ciclo de vida de desenvolvimento de software. Ele permite que várias pessoas trabalhem simultaneamente em um único projeto, cada uma mantendo sua própria cópia do código e escolhendo quando compartilhá-la com o restante da equipe. Para conseguir isso, os desenvolvedores fazem uso de Git repositórios para ajudar com o controle de versão. GitLab é um repositório Git baseado na web que é mais do que uma ferramenta de controle de versão. Além disso, ele fornece ferramentas de DevOps, rastreamento de problemas, integração contínua e implantação.

O GitLab oferece três opções que você pode escolher: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) e GitLab SaaS. GitLab CE e GitLab EE são soluções autogerenciadas. Isso significa que você mesmo baixa, instala e gerencia a instância do GitLab. O GitLab SaaS é hospedado pela GitLab Inc. Assim, você não precisa se preocupar em instalar nada para usá-lo. Você só precisa criar uma conta no GitLab e começar.

Neste tutorial, mostraremos como configurar pipelines de Integração Contínua com GitLab CI para monitorar seus repositórios em busca de alterações e executar testes automatizados para validar o novo código. Começaremos configurando um repositório Git para hospedar o código. Em seguida, configuraremos um processo de CI para monitorar os commits no repositório e iniciaremos um runner de CI para executar os testes em um contêiner Docker isolado.

Pré-requisitos

Para começar, você precisará de um servidor executando o software de controle de versão GitLab. Tanto o GitLab self-managed quanto o SaaS podem executar testes automatizados. No entanto, existem alguns limites em termos de minutos e recursos disponibilizados para seus testes nas opções SaaS gratuitas. Você tem mais liberdade se estiver usando as opções self-managed, pois pode alocar quantos recursos desejar para sua instância do GitLab. Siga nosso tutorial sobre hospedar seus próprios repositórios Git com o GitLab para aprender como configurar sua própria instância do GitLab.

Você precisará de pelo menos um servidor para usar como um GitLab CI runner. No entanto, se quiser, você também pode ter mais servidores. Se você configurou uma instância do GitLab autogerenciada, pode usar o mesmo servidor, mas preferimos configurar um servidor diferente para o CI runner. Este tutorial sobre Como configurar seu servidor Ubuntu é um bom começo.

Você precisará do Docker instalado em seus servidores GitLab CI runner para isolar os ambientes de teste em contêineres Docker. Temos um tutorial sobre Como instalar e operar o Docker no Ubuntu que pode ajudar você a concluir este requisito.

Agora que temos tudo o que precisamos, vamos começar!

Passo 1: Criar um Projeto em uma Instância do GitLab

Começaremos criando um repositório de projeto no GitLab. Vamos basear este tutorial em uma aplicação Node.js. Como não queremos criar os arquivos do projeto do zero, o GitLab oferece uma ferramenta para importar projetos de outros repositórios de controle de versão que iremos utilizar. A aplicação que estamos importando é um simples “hello world” app construído com Express.js – um framework web minimalista para aplicações Node.js. Implementaremos os testes usando Mocha e Chai – estes são frameworks JavaScript usados para testes unitários. O Mocha permite testes assíncronos, relatórios de cobertura de testes e pode ser combinado com outras bibliotecas de asserção. O Chai é uma biblioteca de asserção. Ele pode ser combinado com qualquer framework de teste; no nosso caso, combinaremos o Mocha com o Chai.

Agora que você conhece o básico do nosso projeto, faça login na sua instância do GitLab (seja auto-gerenciada ou SaaS), clique no ícone ‘mais’ na barra de navegação superior e selecione ‘Novo projeto’. Opcionalmente, se você rolar até o topo da página inicial da sua conta, poderá clicar no botão ‘Novo projeto’:

Na página do novo projeto, clique na Importar projeto aba:

Em seguida, na página aberta, clique no Repo por URL botão:

Embora exista uma opção de importação do GitHub, não vamos usá-la, pois ela exige um token de acesso pessoal. Não precisamos configurar tokens de acesso pessoal, já que estamos trabalhando com um repositório público, e a importação apenas com a URL é direta.

Depois disso, copie a seguinte URL e cole-a no campo URL do Repositório Git:

Deve ficar assim:

Deixe o repositório como Privado e clique no botão Criar projeto quando terminar. Aguarde alguns segundos para que o projeto seja importado do GitHub e ele aparecerá entre os seus repositórios do GitLab. O GitLab importa o projeto com os mesmos detalhes do projeto do repositório do GitHub.

Etapa 2: Analisando o arquivo .gitlab-ci.yml

O GitLab CI varre todos os repositórios no GitLab em busca de um arquivo chamado .gitlab-ci.yml para saber como deve executar testes automatizados. No repositório que acabamos de importar, você pode ver um .gitlab-ci.yml arquivo entre os arquivos do projeto. Você pode encontrar mais informações sobre o GitLab CI yml no site oficial deles Referência de palavras-chave para a documentação do arquivo .gitlab-ci.yml.

Na interface do repositório do GitLab, clique no .gitlab-ci.yml arquivo para abri-lo na página do navegador. Deve se parecer com isto:

Observe a indentação das linhas. O arquivo segue uma sintaxe estrita de GitLab CI YAML de configuração para definir as várias ações a serem tomadas, em uma ordem especificada sob certas condições. Para garantir que seus arquivos de configuração estejam corretos, o GitLab fornece um utilitário de teste para validação. Dentro de sua instância do GitLab, no repositório do seu projeto, você pode visitar a interface do CI lint para validar seu .gitlab-ci.yml. Clique em CI/CD no menu de navegação à esquerda e clique no botão CI lint na página que aparece:

As diretivas no arquivo de configuração são discutidas abaixo.

• Imagem Docker base

A primeira linha no arquivo de configuração declara uma imagem Docker que deve ser usada para executar os testes. Como estamos construindo uma aplicação Node.js, vamos usar a imagem Node.js mais recente:

• Estágios

Em seguida, definimos os diferentes estágios pelos quais queremos que nossos testes de integração contínua passem. Temos apenas dois estágios:

Ao definir os nomes dos estágios, os nomes como build ou test são escolhidos aleatoriamente – você pode escolher qualquer nome que desejar. No entanto, você deve ordenar as etapas corretamente porque isso determina o fluxo de execução. No nosso caso, os jobs na build etapa executam antes dos jobs na test etapa. O GitLab runner executará os jobs na mesma etapa em paralelo e esperará que todos os jobs sejam concluídos antes de começar a executar os jobs na próxima etapa.

• Cache

Uma cache definição é incluída para especificar os arquivos e diretórios que serão armazenados em cache ou salvos para uso posterior entre as execuções dos jobs:

Definir o cache ajuda a minimizar o tempo necessário para executar jobs que dependem de recursos que dificilmente mudarão entre as execuções. Nós especificamos o diretório node_modules para ser armazenado em cache. Este é o diretório no qual o npm instala as dependências do projeto.

• Jobs

Temos dois jobs na configuração:

• install_dependencies

Ao nomear jobs, você é livre para escolher qualquer nome. No entanto, é recomendável escolher um nome descritivo, pois eles são usados na interface do usuário do GitLab – isso pode ser útil durante a depuração. Você encontrará a maioria das configurações na web combinando npm install com os comandos no estágio de teste. Nós apenas os separamos para ajudar a demonstrar como os jobs interagem, já que este é um projeto bem pequeno. A diretiva stage marca este job como build – ele é executado no estágio de build.

O script diretiva especifica os comandos a serem executados na execução deste job. Você pode especificar múltiplos comandos adicionando linhas dentro do script bloco. Claro, você precisa ter cuidado com a indentação correta e ter em mente a ordem em que os scripts devem ser executados.

A artifacts diretiva especifica arquivos ou caminhos de diretório para salvar e compartilhar entre as etapas. Novamente, um lembrete de que ordenar as etapas corretamente é crucial para garantir que outros arquivos tenham o que precisam para serem executados. O npm install comando instalará as dependências no node_modules diretório. Ao declará-lo nos artefatos, nós o tornamos disponível para jobs executados em estágios subsequentes. Os arquivos também são disponibilizados na interface do usuário do GitLab se você desejar baixá-los.

• test_with_mocha

Este job é executado no estágio test. Como este job é executado após o job no estágio build ter sido executado, os artefatos declarados no estágio build (que são as dependências do nosso app) estarão disponíveis para o estágio test. O bloco script especifica o npm comandos para executar nossos testes. Primeiro iniciamos nossa aplicação e depois executamos os testes contra a aplicação. A execução desses comandos dispara os comandos especificados no package.json seção do bloco de scripts:
Com isso, você deve ter uma compreensão básica do .gitlab-ci.yml arquivo. Dizemos básica porque este é apenas um aplicativo hello world estático. A seguir, vejamos como podemos disparar uma nova execução de CI.

Passo 3: Disparando uma Execução do GitLab CI

Você ficará feliz em saber que, assim que seu repositório tiver o .gitlab-ci.yml arquivo, quaisquer novos commits que você enviar para ele acionarão uma nova execução de Integração Contínua. No caso de instâncias autogerenciadas do GitLab, se você não tiver configurado um runner do GitLab, a execução do CI será definida como “pending”.

O GitLab SaaS oferece aos usuários alguns runners compartilhados que podem coletar seus jobs e executá-los automaticamente. Isso só é possível se os runners compartilhados estiverem livres e você não tiver excedido sua cota. No GitLab SaaS, você pode escolher se deseja que seu repositório use os runners compartilhados ou não, indo em Configurações > CI / CD do seu projeto página como mostrado na captura de tela abaixo. Nesta página, você também encontrará informações sobre as instruções de instalação do GitLab runner, nas quais nos aprofundaremos na próxima etapa:

Agora, vamos fazer uma pequena alteração para acionar uma execução de CI. Navegue de volta para o seu node_pipeline repositório de projeto do GitLab:

Clique no arquivo README.md destacado acima para visualizá-lo:

Clique no botão ‘Edit’ para abrir o arquivo para edição no navegador e adicione algum texto:

Depois de adicionar algum texto, role para baixo e clique em Commit changes botão para salvar as alterações. Você pode modificar a mensagem de commit como desejar. Ela aparecerá como um título na interface do usuário do GitLab quando o pipeline estiver em execução. Nós a deixamos como Update README.md pois é bastante descritivo:

Depois de fazer o commit das alterações, retorne à página principal do projeto. Você notará um pequeno ícone de pausado anexado ao commit mais recente. Se você passar o mouse sobre o ícone, ele exibirá: ‘Pipeline:pending’:

Isso significa que a execução do CI foi acionada. No entanto, os testes ainda não foram executados. No menu de navegação à esquerda, clique em CI/CD, e depois selecione Pipelines. Isso abrirá uma página mostrando mais detalhes sobre o pipeline. Você pode ver que o CI está pendente e marcado como travado:

Para obter mais detalhes sobre a execução, clique no pendente status. Você verá a visualização abaixo, exibindo as diferentes etapas da execução e os jobs individuais vinculados a cada etapa:

Você também pode clicar em jobs individuais para ver seus detalhes mais específicos, como o que está causando os atrasos. No caso de execuções com falha, é aqui que você verá o que causou a falha do job:

A mensagem indica que o job está travado porque você não configurou nenhum runner ativo que possa executar este job. Faremos isso na próxima etapa. Quando você disponibilizar um runner, o job começará a ser executado automaticamente. Quando um job é executado, você verá a saída nesta interface, bem como os outros artefatos para download gerados quando o job estava em execução.

Etapa 4: Configurando um Serviço de Runner do GitLab CI

Agora é hora de fazer uso do segundo servidor que declaramos na seção de Pré-requisitos deste tutorial. Estaremos instalando e configurando um serviço de runner do GitLab neste servidor. Você pode implantar o serviço para executar várias instâncias de runner para diferentes projetos no GitLab.

Você tem a opção de implantar o runner no mesmo servidor que hospeda sua instância autogerenciada do GitLab. No entanto, para garantir que uma instância não seja limitada por recursos, é preferível configurar uma instância de runner de CI separada. Qualquer que seja a configuração escolhida, o Docker deve estar instalado para isolar os ambientes de teste.

O processo de instalação do runner de CI do GitLab é comparável ao de instalando a instância auto-gerenciada do GitLab. Começamos baixando um script para adicionar o repositório oficial do GitLab às fontes do apt usando o seguinte comando:

Forneça sua senha de root quando solicitado. Em seguida, você pode executar o comando para instalar o runner do GitLab CI mais recente:

O comando acima instala e registra um serviço de runner pronto para ser usado pelos seus projetos.

Passo 5: Obtendo Tokens de Registro e Vinculando o GitLab Runner

Para configurar um runner do GitLab CI para começar a aceitar trabalhos, você precisa de um token de runner do GitLab. Ele é necessário para que o runner se autentique com a sua instância do servidor GitLab. Existem dois tipos de tokens, dependendo de como você deseja usar o runner: específicos de projeto e runner compartilhado.

Runners específicos de projeto são aplicáveis se você tiver requisitos exclusivos para o runner. Por exemplo, se você tiver definições de implantação no seu gitlab-ci.yml com tokens exclusivos, um runner específico pode ser recomendado para se autenticar corretamente no ambiente de implantação. Outra consideração é se as suas etapas de integração contínua têm processos que consomem muitos recursos. Nesse caso, o ideal seria optar por um runner específico do projeto. Observe que um runner específico do projeto não aceita trabalhos de outros projetos.

Runners compartilhados são de uso geral e podem ser usados por vários projetos. A instância do GitLab SaaS hospedada em GitLab Inc possui alguns runners compartilhados que coletarão automaticamente seus pipelines, conforme explicado no Passo Três. Os runners recebem trabalhos de suas configurações com base em um algoritmo que considera o número de trabalhos em execução no momento para cada projeto. Um runner compartilhado é mais flexível do que um runner específico. Ele pode ser configurado a partir da conta de administrador da instância do GitLab. Vamos ver como podemos obter os tokens para ambos os runners.

• Registrando um Runner Específico de Projeto

Para registrar um runner específico de projeto, abra seu projeto em sua instância do GitLab ou conta do GitLab SaaS. No menu de navegação à esquerda, clique no item Configurações e selecione a opção CI/CD:

Depois disso, role para baixo até a Runners seção e clique no botão para expandir a seção:

O lado esquerdo explica como registrar um runner específico do projeto. Esta é uma visualização da instância do GitLab SaaS. Você também pode configurar runners automáticos com o Kubernetes, mas estamos usando o runner manual para este tutorial:

Em seguida, você precisa se concentrar na seção onde o token para este projeto é fornecido. Para uma instância autogerenciada do GitLab, a URL exibirá o domínio do servidor no qual sua instância do GitLab está sendo executada:

Você pode optar por desativar os runners compartilhados para este projeto alternando o interruptor na seção do lado direito sob Runners Compartilhados. Em seguida, copie o token de registro exibido para o seu bloco de notas, pois o usaremos mais tarde.

• Registrando um Runner Compartilhado

Para registrar um runner compartilhado, você precisa fazer login em sua instância autogerenciada do GitLab como administrador. Para acessar o painel de administração, clique no ícone de chave inglesa no menu de navegação superior:

No Painel de Administração, clique em Runners na seção Visão Geral do menu lateral esquerdo. Isso abrirá uma página com as instruções de configuração de Runners Compartilhados:

Copie o token de registro exibido no lado direito sob Configurar um Runner compartilhado manualmente. Você usará o token para registrar o runner na próxima etapa.

• Vinculando um GitLab CI Runner a uma Instância do GitLab

Nesta etapa, você vinculará sua instância do GitLab ao runner de CI. Faça login novamente no servidor onde você instalou o serviço do GitLab runner na Etapa Quatro. Para iniciar o processo de registro do runner, insira o seguinte comando no seu terminal:

O comando fará uma série de perguntas a você:

• Insira o URL da instância do GitLab (por exemplo, https://gitlab.com/):

Forneça o nome de domínio da sua instância do GitLab usando https:// para especificar SSL.

• Insira o token de registro:

Forneça o seu token de registro. É aqui que você escolherá se deseja que este runner seja específico do projeto ou compartilhado. Você só pode fornecer um dos tokens copiados anteriormente para qualquer uma das opções.

• Insira uma descrição para o runner:

Escolha um nome descritivo para o seu runner de CI, pois ele aparecerá na interface do usuário da instância do GitLab.

• Insira um executor: custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Aqui, são fornecidas opções para escolher um executor para executar os jobs. Insira Docker.

• Insira as tags para o runner (separadas por vírgula):

Isto é opcional. Você pode inserir quaisquer nomes de tags, como dependências que este runner inclui. Você pode deixar em branco por enquanto.

• Insira a imagem Docker padrão (por exemplo, ruby:2.6):

Aqui, espera-se que você especifique uma imagem padrão de uso geral usada para executar jobs caso o arquivo gitlab-ci.yml não especifique uma imagem. Insira alpine:latest já que é uma imagem pequena, de uso geral e segura. Pressione enter e o runner será registrado e iniciado automaticamente:

Para visualizar a lista de runners atualmente disponíveis, insira o seguinte comando:

Passo 6: Confirmando que o CI Runner foi Vinculado com Sucesso no GitLab

Em seguida, retorne ao seu navegador e visite a página do seu projeto na instância do GitLab. Dependendo de quantos minutos se passaram desde que você registrou o runner, você poderá ver que o job está em execução no momento:

Ou ele pode ter sido concluído:

Depois disso, navegue até Pipelines página, seja pelo menu esquerdo CI/CD > Pipelines, ou clicando no em execução, aprovado, ou com falha ícone (se o pipeline encontrou erros) para visualizar o estado da execução do CI. Aqui podemos ver que uma das etapas (etapa de build) foi aprovada, enquanto uma ainda está em execução:

Na tabela, sob o cabeçalho Etapas, clique em um dos ícones de etapas para visualizar os jobs associados:

Em seguida, clique em um job no pop-up para visualizar os detalhes:

O job foi executado e você pode ver o progresso quando o npm o comando estava instalando as dependências. No lado direito, você pode visualizar outras informações relacionadas. Você tem a opção de baixar os artefatos do job. Você também pode alternar entre as etapas para visualizar outros jobs a partir do menu suspenso.

Aqui, você pode visualizar nossos casos de teste mostrando quando você seleciona o job na etapa de teste:

Runners disponíveis

No menu lateral esquerdo, se você clicar em Configurações > CI/CD, e expandir os Runners seção, você deverá ver o runner que acabou de registrar. Dependendo se você especificou um token específico do projeto ou um token compartilhado, o runner aparecerá na respectiva seção.

Aqui você pode ver que registramos um token específico do projeto. O runner aparece sob Runners específicos:

Conclusão

Neste tutorial, você aprendeu como automatizar seus testes com o GitLab CI. Começamos configurando um projeto de aplicativo Node.js no GitLab. O projeto incluía alguns casos de teste e um gitlab-ci.yml. Aprendemos que o GitLab usa o gitlab-ci.yml arquivo para determinar o que fazer quando é acionado. O arquivo gitlab-ci.yml é apenas um arquivo de configuração que contém instruções sobre como construir e testar aplicações, escrito no formato YAML que um runner do GitLab CI consegue entender.

Também conseguimos configurar um GitLab CI runner em um host separado. Nós o registramos para receber tarefas de nossas instâncias do GitLab sempre que houver um gatilho. Embora este tenha sido um projeto simples, você pode aproveitar essas informações para configurar pipelines para projetos complexos. As etapas para adicionar um projeto ao GitLab e vincular um GitLab CI runner permanecem as mesmas. O que muda são as instruções e etapas no gitlab-ci.yml arquivo.

Feliz Computação!