GitLab — Repositório, Runner e CI/CD | ADS

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.

Figura 1 — GitLab Server, Runner e pipeline do projeto abjinfo.com.br.

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

Comandos GitLab — referência rápida

Cheatsheet dos comandos mais usados no dia a dia: Git no fluxo GitLab, GitLab Runner e a CLI oficial glab.
Substitua URL, token, branch e caminhos pelos valores do seu projeto.

Área	Comando	Descrição
Git	git clone https://gitlab.com/grupo/projeto.git	Clonar repositório GitLab para a máquina local.
Git	git remote -v	Listar remotes (origin) configurados no projeto.
Git	git remote add origin https://gitlab.com/grupo/projeto.git	Associar o remote origin a um repositório GitLab.
Git	git checkout -b feature/minha-branch	Criar e entrar em uma branch de trabalho.
Git	git status	Ver arquivos alterados, staged e branch atual.
Git	git add .	Incluir alterações no stage para o próximo commit.
Git	git commit -m "mensagem clara do commit"	Registrar commit local com mensagem descritiva.
Git	git push -u origin feature/minha-branch	Enviar branch ao GitLab e definir upstream.
Git	git push origin main	Enviar commits da branch main (dispara pipeline se houver CI).
Git	git pull origin main	Atualizar a branch local com o remoto.
Git	git fetch --all --prune	Buscar branches remotas e remover referências obsoletas.
Git	git merge main	Integrar alterações de main na branch atual.
Git	git tag -a v1.0.0 -m "Release 1.0.0"	Criar tag anotada (útil para releases e pipelines por tag).
Git	git push origin v1.0.0	Publicar tag no GitLab.
Git	git log --oneline --graph -n 20	Histórico resumido de commits.
Runner	gitlab-runner --version	Exibir versão instalada do GitLab Runner.
Runner	gitlab-runner register	Registrar runner (URL do GitLab, token, tags e executor).
Runner	gitlab-runner register --non-interactive --url URL --token TOKEN --executor shell --tag-list windows	Registro não interativo com tags e executor definidos.
Runner	gitlab-runner install	Instalar o runner como serviço do sistema (Windows/Linux).
Runner	gitlab-runner start	Iniciar o serviço do runner.
Runner	gitlab-runner stop	Parar o serviço do runner.
Runner	gitlab-runner restart	Reiniciar o serviço do runner.
Runner	gitlab-runner status	Verificar se o serviço do runner está em execução.
Runner	gitlab-runner verify	Validar conexão dos runners registrados com o GitLab.
Runner	gitlab-runner list	Listar runners configurados neste host.
Runner	gitlab-runner run	Executar o runner em primeiro plano (debug).
Runner	gitlab-runner unregister --name "nome-do-runner"	Remover registro de um runner específico.
Runner	gitlab-runner unregister --all-runners	Remover todos os runners registrados neste host.
Runner	gitlab-runner uninstall	Remover o serviço do runner do sistema.
glab	glab auth login	Autenticar a CLI glab no GitLab (token/hostname).
glab	glab auth status	Verificar conta e host autenticados.
glab	glab repo clone grupo/projeto	Clonar projeto via glab.
glab	glab repo view	Abrir/ver detalhes do repositório atual.
glab	glab mr create --title "Título" --description "Descrição"	Abrir Merge Request a partir da branch atual.
glab	glab mr list	Listar Merge Requests do projeto.
glab	glab mr view <iid>	Ver detalhes de um Merge Request.
glab	glab mr checkout <iid>	Baixar e entrar na branch de um MR.
glab	glab mr merge <iid>	Mesclar Merge Request (respeitando regras do projeto).
glab	glab mr close <iid>	Fechar Merge Request sem mesclar.
glab	glab ci status	Status da pipeline da branch/commit atual.
glab	glab ci view	Abrir visualização da pipeline no terminal/browser.
glab	glab ci trace <job-id>	Acompanhar log (trace) de um job da pipeline.
glab	glab ci run	Disparar pipeline manualmente.
glab	glab ci lint	Validar a sintaxe do .gitlab-ci.yml.
glab	glab issue list	Listar issues do projeto.
glab	glab issue create --title "Título"	Criar issue no GitLab.
glab	glab release list	Listar releases publicadas.
glab	glab api projects/:id/pipelines	Chamar a API REST do GitLab a partir da CLI.
CI/CD	echo $CI_COMMIT_BRANCH	Variável: nome da branch do commit (Linux/bash).
CI/CD	echo $env:CI_COMMIT_BRANCH	Variável: nome da branch do commit (PowerShell/Windows).
CI/CD	echo $CI_COMMIT_SHA	Variável: hash completo do commit.
CI/CD	echo $CI_PROJECT_DIR	Variável: diretório de trabalho do job no runner.
CI/CD	echo $CI_PIPELINE_ID	Variável: ID da pipeline em execução.
CI/CD	echo $CI_JOB_NAME	Variável: nome do job atual.
CI/CD	echo $CI_REGISTRY_IMAGE	Variável: imagem padrão no Container Registry do projeto.
CI/CD	docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY	Autenticar no Container Registry do GitLab dentro do job.
CI/CD	git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/grupo/projeto.git	Clonar outro repo na pipeline com CI_JOB_TOKEN.

GitLab — Repositório, Runner e CI/CD

O que é GitLab

Componentes da arquitetura

Instalação do GitLab Runner

Configurando uma pipeline CI/CD

Exemplo visual — fluxo GitLab CI/CD

Boas práticas

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

Comandos GitLab — referência rápida

Vídeo — Pipeline CI/CD com GitLab