# Fluxo de Processamento

O GitOps processa releases atraves de tres gatilhos: webhook, scheduler e manual.

# Gatilhos

# 1. Webhook (Instantaneo)

GitHub  ──► POST /webhook/github  ──►  Validacao HMAC  ──►  Processamento

Quando voce publica um release, o GitHub envia um evento para o endpoint de webhook. O GitOps valida a assinatura HMAC SHA256 e processa imediatamente.

# 2. Scheduler (Polling)

APScheduler  ──►  Lista repos ativos  ──►  Busca latest release  ──►  Processamento
              (a cada N minutos)           (GitHub API)              (se nao processado)

O scheduler verifica periodicamente todos os repositorios ativos. Configuravel via cron ou intervalo fixo.

# 3. Manual (API/Dashboard/MCP)

Usuario  ──►  POST /monitor/check/{owner}/{repo}  ──►  Processamento
              POST /monitor/reprocess/{owner}/{repo}

O usuario pode forcar uma verificacao ou reprocessamento via API, Dashboard ou MCP.

# Pipeline de Processamento

Quando um release e detectado, o GitOps executa:

1. Verificar duplicata
   └── Release ja processado? → Skip

2. Carregar configuracao
   └── Baixar .gitops.yml do repo na tag
   └── Merge com defaults

3. Processar release assets
   └── Para cada asset do GitHub Release:
       └── Baixar via API (com token)
       └── Upload para B2 (versionado + latest)

4. Processar artefatos (.gitops.yml)
   └── Para cada artifact configurado:
       ├── source: "asset:file.zip:inner" → Extrair de ZIP
       ├── source: "asset:file" → Usar asset direto
       └── source: "path/file" → Baixar do repo
       └── type: binary → Upload direto
       └── type: zip → Criar ZIP e upload

5. Processar documentacao
   └── Para cada doc configurado:
       └── Baixar do repo (README, MANUAL, CHANGELOG)
       └── Upload latest + versionado

6. Registrar no banco
   └── JSON com assets + artifacts + docs

7. Notificar
   └── Telegram com resumo do release

# Deteccao de Canal

Para projetos com canais (stable/rc), o GitOps detecta automaticamente:

# .gitops.yml
channels:
  stable:
    tag_pattern: "v[0-9]+.[0-9]+.[0-9]+$"     # v1.2.3
    folder: ""
  rc:
    tag_pattern: "v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+$"  # v1.2.3-rc.1
    folder: "rc"

Tag v1.2.3      → canal stable → path: ""     → runner.ccs.systems/runner
Tag v1.2.3-rc.1 → canal rc     → path: "rc/"  → runner.ccs.systems/rc/runner

# Fontes de Artefatos

O GitOps suporta tres tipos de fonte:

# Arquivo do Repositorio

source: meu-binario    # Busca arquivo "meu-binario" na tag

Usa a API de contents do GitHub. Suporta arquivos ate ~100MB (com fallback para download_url e Git Blobs API para arquivos >1MB).

# Asset Direto

source: asset:projeto.zip    # Usa ZIP do release direto

Baixa o asset anexado ao GitHub Release.

# Extracao de ZIP

source: asset:projeto.zip:binario    # Extrai "binario" de dentro do ZIP

Baixa o ZIP do release e extrai o arquivo especificado de dentro.

# Estrutura de Destino no B2

{bucket}/{folder_name}/{destination}

Exemplo com folder_name: runner:

ccs-systems/runner/runner            ← latest binary
ccs-systems/runner/runner.zip        ← latest zip
ccs-systems/runner/latest/runner     ← latest directory
ccs-systems/runner/v1.2.3/runner     ← versioned
ccs-systems/runner/rc/runner         ← latest RC
ccs-systems/runner/rc/v1.2.3-rc.1/runner  ← versioned RC
ccs-systems/runner/docs/latest/README.md
ccs-systems/runner/docs/v1.2.3/README.md

# Transformacao de URL (CDN)

O GitOps transforma URLs do B2 para URLs CDN:

B2:  https://f006.backblazeb2.com/file/ccs-systems/runner/runner
CDN: https://runner.ccs.systems/runner

A transformacao usa delivery_url e folder_name do .gitops.yml:

• Remove o prefixo B2 (/file/{bucket}/)
• Remove o folder_name do path (ja incluso no subdominio CDN)
• Prefixa com delivery_url

# Prevencao de Duplicatas

O GitOps rastreia releases processados por (repo_id, tag_name). Se um release ja foi processado:

• check: Skip silencioso
• reprocess: Deleta registro e reprocessa
• force_reprocess: Aceita tag especifica para reprocessar