Skip to content

GitLab

Last edited by Saccilotto
Page history

Repositorios

Repositórios do Projeto

Home Escopo Processo Sprints Design Arquitetura Repositorios Gerencia Banco de Dados

Última atualização: 19 de Outubro 2025

Estrutura de Repositórios

O projeto Pró-Mata utiliza uma estrutura híbrida GitLab (oficial) + GitHub (desenvolvimento):

  • GitLab: Repositórios oficiais (requisito institucional AGES)
  • GitHub: Desenvolvimento ativo (familiaridade da equipe, ferramentas)
  • Sincronização: Automática GitHub → GitLab

Repositórios Oficiais (GitLab)

Frontend

URL: https://tools.ages.pucrs.br/pro-mata/frontend

Descrição: Interface Web do usuário (React 19 + TypeScript)

Tecnologias Principais:

  • React 19
  • Vite 6
  • TanStack Router (file-based routing)
  • TanStack Query (server state)
  • Tailwind CSS 4
  • Shadcn/UI + Radix UI
  • Vitest (unit/integration) + Playwright (E2E)

Estrutura:

src/
├── components/ui/    # Shadcn/UI components
├── features/         # Feature modules
├── lib/              # Utilities
├── routes/           # TanStack Router (file-based)
├── styles/           # Tailwind + tokens
└── main.tsx          # App bootstrap

Scripts Principais:

  • npm run dev: Dev server (hot reload)
  • npm run build: Build produção
  • npm run test: Testes unitários (Vitest)
  • npm run test:e2e: Testes E2E (Playwright)

Deploy: AWS S3 static hosting (via GitHub Actions)

Backend

URL: https://tools.ages.pucrs.br/pro-mata/backend

Descrição: API REST (NestJS + Node.js 22)

Tecnologias Principais:

  • NestJS (framework)
  • Node.js 22
  • TypeScript (strict mode)
  • Prisma ORM + PostgreSQL 15
  • JWT (autenticação)
  • Zod (validação)
  • Swagger (documentação API)
  • Jest (testes)

Estrutura:

src/
├── analytics/        # Umami integration
├── auth/             # JWT auth + roles
├── database/         # Prisma client
├── user/             # User management
├── experience/       # Experiences CRUD
└── main.ts           # App bootstrap

prisma/
├── schema.prisma     # Database schema
└── migrations/       # Database migrations

Scripts Principais:

  • npm run dev: Dev server (hot reload)
  • npm run build: Build produção
  • npm run test: Testes unitários (Jest)
  • npm run prisma:migrate: Rodar migrations
  • npm run prisma:generate: Gerar Prisma Client

Deploy: AWS EC2 (Docker container via GitHub Actions)

Documentação API: https://api.pro-mata.exemplo.com/api (Swagger)

Infraestrutura

URL: https://tools.ages.pucrs.br/pro-mata/infrastructure

Descrição: Configuração de infraestrutura (scripts, configs)

Conteúdo:

  • Scripts de deploy
  • Configurações AWS
  • Docker Compose files
  • Documentação de infraestrutura

Nota: Infraestrutura atual simplificada (AWS S3 + EC2). Ver repositório de backup para stack completa.

Repositórios Desenvolvimento (GitHub)

Frontend (GitHub)

URL: https://github.com/AGES-Pro-Mata/frontend

Status: Desenvolvimento ativo (mirror → GitLab)

Acesso: Privado (membros org AGES-Pro-Mata)

CI/CD:

  • Trigger: Push em main
  • Pipeline: Lint → Test → Build → Deploy S3
  • Ferramentas: GitHub Actions

Backend (GitHub)

URL: https://github.com/AGES-Pro-Mata/backend

Status: Desenvolvimento ativo (mirror → GitLab)

Acesso: Privado (membros org AGES-Pro-Mata)

CI/CD:

  • Trigger: Push em main
  • Pipeline: Lint → Test → Build → Docker → Deploy EC2
  • Registry: Docker Hub (imagens públicas)

Issues e Projects

GitHub Projects: https://github.com/orgs/AGES-Pro-Mata/projects/1

Acesso: Privado (apenas membros org AGES-Pro-Mata)

Kanban: Backlog → To Do → In Progress → Review → Done

Sincronização Issues: GitHub Issues → GitLab Issues (automatizada, simplificada)

Observação: O board kanban é gerenciado no GitHub Projects privado. Milestones são usados para tracking de Sprints:

  • Sprint 4 Backend: 40% (3 issues abertas, 2 fechadas)
  • Sprint 4 Frontend: 47% (10 issues abertas, 9 fechadas)
  • Prazo Sprint 4: 17/11/2025 (entrega), 19/11/2025 (apresentação)

CI/CD de Sincronização: GitHub → GitLab (automatizado via GitHub Actions)

  • Código: Mirror completo em tempo real (branches, commits, tags)
  • Issues: Sincronização automatizada para documentação e histórico
  • Kanban/Projects: Não sincronizado (GitHub Projects privado é fonte única)
  • Wiki: Atualização manual no GitLab (documentação oficial)
  • Propósito: Manter histórico completo no GitLab para fins institucionais AGES, enquanto desenvolvimento ativo ocorre no GitHub

Repositório de Backup (Infraestrutura Multi-Cloud)

Infra Multi-Cloud (Azure + AWS)

URL: https://github.com/Saccilotto/pro-mata-infra

Owner: André Sacilotto Santos (AGES IV - pessoal)

Status: Standby (não utilizado em produção atual)

Descrição: Infraestrutura completa multi-cloud com Terraform + Ansible + Docker Swarm

Stack:

  • IaC: Terraform (Azure VMs / AWS EC2)
  • CaC: Ansible (Docker Swarm config)
  • Orquestração: Docker Swarm
  • Proxy/LB: Traefik v3
  • Observabilidade: Prometheus + Grafana
  • CDN/WAF: Cloudflare
  • Domínio: registro.br

Estrutura:

iac/                  # Terraform (Infrastructure as Code)
cac/                  # Ansible (Configuration as Code)
docker/               # Dockerfiles e Compose
envs/                 # Environment configs
scripts/              # Deployment scripts
docs/                 # Documentation

Propósito: Redundância geográfica, backup, tolerância a falhas (RTO < 4h)

Sincronização Automatizada

Visão Geral do CI/CD de Sincronização

O projeto utiliza pipelines automatizados de CI/CD (GitHub Actions) para manter o GitLab como repositório oficial de documentação e histórico, enquanto o desenvolvimento ativo ocorre no GitHub.

Motivação:

  • GitLab: Repositório oficial institucional AGES (requisito, auditoria, transparência)
  • GitHub: Plataforma de desenvolvimento (familiaridade da equipe, ferramentas, Projects privado)
  • Sincronização automática: Garante conformidade institucional sem duplicar trabalho manual

GitHub → GitLab (Código)

Ferramenta: GitHub Actions (mirror workflow)

Trigger: Push em main, develop ou feature/*

Frequência: Tempo real (a cada push)

Pipeline:

1. Push no GitHub (qualquer branch)
   ↓
2. GitHub Actions detecta evento
   ↓
3. Workflow de mirror executa
   ↓
4. Git push --mirror para GitLab
   ↓
5. GitLab atualizado (branches, commits, tags)

Conteúdo Sincronizado:

  • ✅ Código-fonte (todos os arquivos)
  • ✅ Branches (main, develop, feature/*)
  • ✅ Commits (histórico completo com mensagens)
  • ✅ Tags (releases e versões)
  • ✅ Histórico de merge/rebase

Latência: < 2 minutos

Logs: Disponíveis em GitHub Actions (repositório → Actions → Mirror Workflow)

GitHub Issues → GitLab Issues

Ferramenta: GitHub Actions (custom script Python)

Trigger: Criação, atualização ou fechamento de issue

Frequência: Tempo real (webhook-based)

Pipeline:

1. Issue criada/atualizada no GitHub
   ↓
2. Webhook dispara GitHub Actions
   ↓
3. Script Python processa issue
   ↓
4. GitLab API cria/atualiza issue espelhada
   ↓
5. Link bidirecional adicionado (GitHub ↔ GitLab)

Conteúdo Sincronizado:

  • ✅ Título e descrição
  • ✅ Labels (mapeamento automático)
  • ✅ Status (aberta/fechada)
  • ✅ Milestones (Sprint 1, 2, 3, 4)
  • ⚠️ Comentários (resumo simplificado)
  • ❌ Assignees (não sincronizado)
  • ❌ GitHub Projects (board privado, não exportado)

Mapeamento de Labels:

GitHub GitLab
bug bug
feature enhancement
frontend frontend
backend backend
documentation documentation

Nota: Sincronização simplificada para fins de documentação e histórico institucional. Para gestão de tarefas ativa, usar GitHub Issues/Projects.

GitHub Projects → GitLab (Não Sincronizado)

Status: ❌ Não sincronizado automaticamente

Motivo:

  • GitHub Projects é privado (apenas membros org AGES-Pro-Mata)
  • GitLab não possui ferramenta equivalente configurada
  • Kanban é fonte única no GitHub

Alternativa para Documentação:

  • Milestones sincronizados (Sprint 1, 2, 3, 4) servem como tracking no GitLab
  • Wiki GitLab documenta progresso das sprints manualmente
  • Métricas consolidadas em Sprints

Diagrama de Fluxo CI/CD de Sincronização

┌─────────────────────────────────────────────────────────────┐
│              DESENVOLVIMENTO ATIVO (GitHub)                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐     │
│  │   Código     │   │    Issues    │   │   Projects   │     │
│  │ (repos dev)  │   │ (tracking)   │   │   (kanban)   │     │
│         │                  │                  │             │
│         │ push             │ webhook          │ (privado)   │
│         ↓                  ↓                  ↓             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         GitHub Actions (CI/CD Workflows)            │    │
│  │  • mirror-workflow.yml (código)                     │    │
│  │  • sync-issues.yml (issues)                         │    │
│  └─────────────┬───────────────┬───────────────────────┘    │
│                │               │                            │
└────────────────┼───────────────┼────────────────────────────┘
                 │               │
    git push     │               │ GitLab API
    --mirror     │               │ (create/update)
                 ↓               ↓
┌─────────────────────────────────────────────────────────────┐
│     DOCUMENTAÇÃO E HISTÓRICO OFICIAL (GitLab AGES)          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐     │
│  │   Código     │   │    Issues    │   │     Wiki     │     │
│  │  (mirror)    │   │  (espelho)   │   │   (manual)   │     │
│  │   ✅ sync   │   │   ✅ sync    │   │   (manual)   │     │
│  └──────────────┘   └──────────────┘   └──────────────┘     │
│                                                             │
│  Propósito: Auditoria, Transparência, Requisito AGES        │
└─────────────────────────────────────────────────────────────┘

Fluxo Resumido:

  1. Desenvolvedor: Push código ou cria issue no GitHub
  2. GitHub Actions: Detecta evento e executa workflow automático
  3. Sincronização: Mirror de código e espelhamento de issues para GitLab
  4. GitLab: Mantém histórico completo para fins institucionais
  5. Wiki: Atualização manual semanal com métricas consolidadas

Ferramentas de Monitoramento:

  • GitHub Actions logs: github.com/AGES-Pro-Mata/{repo}/actions
  • GitLab mirror status: tools.ages.pucrs.br/pro-mata/{repo}
  • Webhook delivery: GitHub Settings → Webhooks

Workflow de Desenvolvimento

1. Desenvolvimento (GitHub)

# 1. Criar branch feature
git checkout -b feature/42-login-jwt

# 2. Desenvolver + commits semânticos
git commit -m "feat: adiciona autenticação JWT"

# 3. Push para GitHub
git push origin feature/42-login-jwt

# 4. Abrir Pull Request (GitHub)
# - Target: develop
# - Reviewers: AGES III/IV (mín. 2)

# 5. CI/CD valida automaticamente
# - Lint (ESLint + Prettier)
# - Test (Vitest/Jest)
# - Build (TypeScript)

# 6. Merge após aprovação
# - GitHub: merge PR
# - GitLab: mirror automático

2. Deploy (Automático)

# Após merge em main (GitHub):
# 1. CI/CD build produção
# 2. Frontend → AWS S3
# 3. Backend → Docker Hub → AWS EC2
# 4. Mirror → GitLab

Convenções

Branches

Nomenclatura: feature/[numero-issue]-[descricao]

Exemplos:

  • feature/42-login-jwt
  • feature/15-reservas-crud
  • feature/8-admin-dashboard

Commits

Padrão: Conventional Commits

Formato: tipo: descrição

Tipos:

  • feat: Nova funcionalidade
  • fix: Correção de bug
  • docs: Documentação
  • style: Formatação (sem lógica)
  • refactor: Refatoração
  • test: Testes
  • chore: Manutenção (deps, config)

Exemplos:

git commit -m "feat: adiciona autenticação JWT no backend"
git commit -m "fix: corrige validação de datas em reservas (#15)"
git commit -m "docs: atualiza README com instruções de setup"

Pull Requests

Template:

## Descrição
[O que foi implementado]

## Issue Relacionada
Closes #42

## Tipo de Mudança
- [ ] Nova funcionalidade
- [ ] Correção de bug
- [ ] Breaking change
- [ ] Documentação

## Checklist
- [ ] Testes passando
- [ ] Code review feito
- [ ] Documentação atualizada

Acesso aos Repositórios

GitLab (Oficial)

Acesso: Público (leitura) / Privado (escrita - membros AGES)

Login: Credenciais institucional PUCRS

URL Base: https://tools.ages.pucrs.br

GitHub (Desenvolvimento)

Acesso: Privado (apenas membros org AGES-Pro-Mata)

Convite: Solicitar a AGES IV

URL Base: https://github.com/AGES-Pro-Mata

Backup (Pessoal)

Acesso: Público (leitura)

Owner: André Sacilotto Santos

URL: https://github.com/Saccilotto/pro-mata-infra

Links Rápidos

Repositórios

Gestão

Documentação

Troubleshooting

Problemas Comuns

1. Erro ao clonar repositório GitLab

# Solução: Verificar credenciais PUCRS
git config --global credential.helper store
git clone https://tools.ages.pucrs.br/pro-mata/frontend.git

2. CI/CD falhando

  • Verificar linter: npm run lint
  • Verificar testes: npm run test
  • Verificar build: npm run build

3. Docker build falhando (backend)

# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up

4. Prisma migrations out of sync

# Backend: sincronizar schema
npm run prisma:migrate deploy
npm run prisma:generate

Última Revisão: 15 de Novembro 2025 Responsável: AGES III (Arquitetura) + AGES IV (Gerência)