GitLab CI/CD

Introdução

O GitLab CI/CD é uma ferramenta integrada ao GitLab onde é possível descrever todos os passos de integração e implantação contínua em um arquivo dentro do repositório. Na SETIC é utilizado para automatizar os processos de integração, inspeção de código e publicação no OpenShift.

Orientações

Pré-requisitos

Docker

A esteira de automação da SETIC, que utiliza o Gitlab CI/CD, é baseada na adoção de Containers, com isso, dentre as opções disponíveis no mercado, foi escolhido a ferramenta Docker.

Todo projeto deverá possuir um arquivo "Dockerfile" ou "Containerfile" funcional.

Certificados

Alguns certificados são necessários para que o projeto possa ser publicado no OpenShift.

Abaixo segue o exemplo, baseado em uma imagem Linux (Alpine, Debian, Ubuntu e distribuições derivadas)

RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/openshift_ca.crt -o /usr/local/share/ca-certificates/openshift_ca.crt
RUN curl -fsSL https://gitlab.setic.ro.gov.br/publico/ca-trust/-/raw/master/portainer_ca.crt -o /usr/local/share/ca-certificates/portainer_ca.crt
RUN update-ca-certificates

Abaixo segue o exemplo, baseado em uma imagem Windows

Em andamento...

Instalação

Crie um arquivo "gitlab-ci.yml" na raiz do projeto, com a estrutura básica abaixo.

include:
  - project: ci-cd/templates
    ref: production
    file:
      - deploy.openshift.yml
      - variables.yml

stages:
  - deploy

variables:
  PROJECT_NAME: "nomedoprojeto"
  PROJECT_DISPLAY_NAME: "Nome do Projeto"

  ## DOCKER
  DOCKERFILE_PATH: "Dockerfile"
  DOCKERFILE_CONTEXT: "/"

  ## ROTA
  ROUTER_PORT: "8080"
  ROUTER_PATH: "/"
  ROUTER_TERMINATION: "reencrypt"

  ## CERTIFICADOS
  CERTIFICATE_SECRET_NAME: "openshift-tls"
  CERTIFICATE_MOUNT_PATH: "/var/run/secrets/service-cert"

  ## ROTAS EXTRAS
  ROUTER_HOSTNAME_DEVELOPMENT: ""

  ROUTER_HOSTNAME_STAGING: >
    "rotaexternaqa.exemplo.com"

  ROUTER_HOSTNAME_PRODUCTION: >
    "rotaexternaproducao.exemplo.com"

  ## VARIAVEIS DE AMBIENTE DEPLOY
  DEPLOY_ENVIRONMENT: >
    "TZ=America/Porto_Velho"

Trecho Include

Este trecho referencia os arquivos de configuração da esteira de automação. Por padrão é incluído o arquivo de configuração de deploy junto com arquivo de variáveis necessárias para o funcionamento da esteira.

Trecho Stages

Este trecho especifica quais estágios do arquivo serão utilizados no processo de execução da esteira.

Trecho Variables

Este trecho é responsável por incluir variáveis pertinentes ao projeto para a execução da esteira, sendo customizável para cada projeto.

PROJECT_NAME

Essa variável configura o nome do projeto que será criado no OpenShift, também será utilizada internamente por operações do OpenShift, como por exemplo, para criação de rotas internas.

O valor da variável deve possuir apenas letras minúsculas, sem acento ou espaço.

PROJECT_DISPLAY_NAME

Essa variável será o nome "amigável" do projeto no OpenShift.

É permitido qualquer valor alfanumérico, incluindo espaço, símbolos e acentos.

DOCKERFILE_PATH

Variável que indica onde está localizado o arquivo Dockerfile do projeto.

É suportado arquivo "Dockerfile", "Containerfile" ou qualquer outro arquivo que seja suportado pela Docker Engine.

DOCKERFILE_CONTEXT: "/"

## ROTA
ROUTER_PORT: "8080"
ROUTER_PATH: "/"
ROUTER_TERMINATION: "reencrypt"

## CERTIFICADOS
CERTIFICATE_SECRET_NAME: "openshift-tls"
CERTIFICATE_MOUNT_PATH: "/var/run/secrets/service-cert"

Explica aí, Jão.

ROUTER_HOSTNAME_DEVELOPMENT, ROUTER_HOSTNAME_STAGING, ROUTER_HOSTNAME_PRODUCTION

Representação das rotas externas do projeto, caso possuam. São separadas por ambientes, sendo eles: Development, Staging e Production.

Essa variável suporta uma lista de URLs, caso seu projeto possua mais de uma.

As URLs inseridas devem ser apenas externas. As URLs internas, são criadas automaticamente pela esteira de automação, sem a necessidade de especifica-las.

Não devem possuir protocolo e devem conter apenas a URL base, sem diretórios.

DEPLOY_ENVIRONMENT

Nessa variável é possível especificar variáveis que serão utilizadas no Deployment do container.

Atualmente utilizamos para inserir variáveis de configurações do Container, como por exemplo, configurar a timezone do container.

Enriquecendo a configuração do CI

Trecho Include

Code-Quality

Além dos arquivos de deploy e variables, existe o "code-quality.{linguagem}.yml", que é o arquivo responsável pela configuração do pipeline de inspeção de código. Atualmente a ferramenta utilizada para inspeção de códigos é o SonarQube.

Exemplo de inserção:

include:
  - project: ci-cd/templates
    ref: production
    file:
      - code-quality.dotnet.yml
      - deploy.openshift.yml
      - variables.yml

Linguagens suportadas:
- .NET (dotnet)

Suporte a outras linguagens serão desenvolvidas conforme a necessidade.

Trecho Stage

Code-Quality

Além do stage de deploy, existe o code-quality, que é o estágio responsável por executar o processo de inspeção de código.

Exemplo de inserção:

stages:
  - code-quality
  - deploy

Trecho Variables

PROJECT_SDK (.NET)

Esta variável especifica a versão .NET utilizada no projeto, para ser utilizada no processo de inspeção de código.

Versões de SDKs .NET suportadas:
- 3.1
- 5.0
- 6.0

Esta variável é obrigatória para projetos .NET

Suporte a outros SDKs serão desenvolvidos conforme a necessidade.

PROJECT_SOLUTION (.NET)

Esta variável especifica o arquivo .SLN, sendo necessário para execução do comando build do .NET.

Esta variável é obrigatória para projetos .NET

BUILD_ENVIRONMENT

Nessa variável é possível especificar variáveis que serão utilizadas no Build do projeto.

Exemplo de inserção:

BUILD_ENVIRONMENT: >
  "DOTNET_RESTORE_DISABLE_PARALLEL=True"
  "DOTNET_INCREMENTAL=True"
  "DOTNET_VERBOSITY=diag"

Atualmente utilizamos para inserir variáveis de configurações do Container referentes a linguagem.

BUILD_ENVIRONMENT_FILE

Nessa variável é especificado o arquivo .ENV caso seu projeto possua um.

Para facilitar o uso dinâmico baseado em ambientes distintos, é possível utilizar a variável CI_COMMIT_REF_NAME do GitLab-CI para obter o nome da branch onde o estágio está sendo executado, como por examplo:
BUILD_ENVIRONMENT_FILE: "${CI_COMMIT_REF_NAME}.env"
Se for executado na branch development, será obtido o resultado: development.env.

Caso queira conhecer mais variáveis pré-definidas no GitLab, acesse: ~~https://docs.gitlab.com/ee/ci/variables/predefined_variables.html~~Variáveis pré-definidas do GitLab-CI