GitLab — Repositório, Runner e CI/CD

O que é GitLab

• GitLab é uma plataforma DevOps que reúne repositório Git, issues, merge requests (MR), wiki, registry de containers e CI/CD nativo.
• Self-hosted (GitLab CE/EE no seu servidor) ou SaaS (gitlab.com) — o fluxo de trabalho é o mesmo.
• Cada projeto tem branches protegidas, revisão de código via MR e pipelines automáticas a cada push.
• No Sistema de Atividades, o GitLab versiona o código da API exportar-pdf (RF-012) e publica em produção só após pipeline verde na branch main.

Componentes da arquitetura

• GitLab Server: interface web, repositórios, definição de pipelines e variáveis CI/CD.
• GitLab Runner: agente que executa os jobs — pode ser compartilhado (grupo) ou dedicado (projeto).
• .gitlab-ci.yml: arquivo na raiz do repo que declara stages, jobs, rules e scripts (pipeline como código).
• Executor: shell (comandos no SO), docker (container efêmero) ou kubernetes — escolhido no registro do runner.
• Tags: rotulam runners (ex.: windows, linux, docker) para direcionar jobs à máquina correta.
• Variáveis CI/CD: secrets (SSH, tokens) configuradas em Settings → CI/CD → Variables — nunca no código.

Instalação do GitLab Runner

• No GitLab: Settings → CI/CD → Runners → New project runner → copie URL e token de registro.
• Linux (Debian/Ubuntu): repositório oficial → apt install gitlab-runner → gitlab-runner register → systemctl enable gitlab-runner.
• Windows: baixe gitlab-runner.exe, instale como serviço (gitlab-runner install) e registre com executor shell.
• Registro interativo: informe URL do GitLab, token, descrição, tags (ex.: windows) e executor (shell para PowerShell nativo).
• Verifique em Runners se aparece verde (online) antes de disparar a primeira pipeline.
• Runner dedicado na máquina de deploy evita expor credenciais SFTP/SSH em runners compartilhados públicos.

Configurando uma pipeline CI/CD

• stages: ordem lógica (validate → test → build → deploy) — jobs do mesmo stage rodam em paralelo.
• Cada job define stage, script (comandos), rules (quando executar) e tags (qual runner usar).
• rules: - if: '$CI_COMMIT_BRANCH == "main"' limita deploy à branch de produção.
• Gatilhos: push, merge request, tag, pipeline manual ou agendada (schedules).
• Artefatos e cache: preserve build/test output entre jobs; cache acelera dependências (npm, composer).
• Proteção de branch: MR obrigatório + pipeline verde antes do merge em main.

Exemplo visual — fluxo GitLab CI/CD

• Do commit no repositório até o deploy automatizado via runner com tag windows.

Boas práticas

• Pipeline enxuta: validação rápida no MR; deploy pesado só em main.
• Variáveis mascaradas e protegidas para senhas SFTP/SSH; tipo File para chaves privadas.
• Tags explícitas nos jobs — evita job rodando no runner errado.
• Retry e timeout em jobs de rede (deploy SFTP) para falhas transitórias.
• Logs de pipeline versionados — cada job mostra stdout; falha deve ser reproduzível localmente.
• Runner atualizado e isolado: usuário de serviço dedicado, firewall e least privilege no servidor de deploy.

Modelo textual — instalação runner + .gitlab-ci.yml

• Roteiro resumido para runner Windows e pipeline validate + deploy SFTP (como abjinfo.com.br).

────────────────────────────────────────────────────────────
GITLAB RUNNER + CI/CD — ROTEIRO DE CONFIGURAÇÃO
────────────────────────────────────────────────────────────

1. CRIAR RUNNER NO GITLAB
   Projeto → Settings → CI/CD → Runners → New project runner
   SO: Windows | Tags: windows | Executor: shell

2. INSTALAR RUNNER (Windows — PowerShell admin)
   mkdir C:\GitLab-Runner
   # Baixar gitlab-runner.exe para C:\GitLab-Runner
   cd C:\GitLab-Runner
   .\gitlab-runner register
     URL:      https://gitlab.seudominio.com.br/
     Token:    [token gerado na UI]
     Tags:     windows
     Executor: shell
   .\gitlab-runner install
   .\gitlab-runner start

3. VARIÁVEIS CI/CD (Settings → CI/CD → Variables)
   SSH_HOST        (masked)
   SSH_USER        (masked)
   SSH_PASSWORD    (masked, protected)
   DEPLOY_PATH     ex.: /var/www/abjinfo.com.br
   WINSCP_PATH     opcional — caminho do WinSCP.com

4. ARQUIVO .gitlab-ci.yml (raiz do repositório)
────────────────────────────────────────────────────────────
stages:
  - validate
  - deploy

default:
  tags:
    - windows

validate_page:
  stage: validate
  script:
    - if (-not (Test-Path "index.php")) { throw "index.php nao encontrado" }
    - if (-not (Test-Path ".htaccess")) { throw ".htaccess nao encontrado" }

deploy_sftp:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - # sincronizar via WinSCP/SFTP para $env:DEPLOY_PATH
────────────────────────────────────────────────────────────

5. CHECKLIST ANTES DO PRIMEIRO DEPLOY
  [ ] Runner online (verde) com tag windows
  [ ] Variáveis preenchidas e protegidas
  [ ] Branch main protegida (MR + pipeline obrigatória)
  [ ] Teste manual: CI/CD → Run pipeline na branch test-deploy
  [ ] Deploy em main validado; rollback = redeploy commit anterior