Colliers × Costal — Interno

Runbook — Publicar / ressincronizar wikis

Leitura de 4 min

Runbook | Publicar / Ressincronizar Wikis

runbook publicacao governanca

Como o pipeline de publicação funciona e o que fazer quando ele falha.

Visão geral do pipeline

Vault Obsidian (Google Drive) 
        │
        │  rclone sync 3x/dia + on-push
        ▼
  GitHub repo (colliers-costal-wiki) → content/
        │
        │  quartz build --matrix [internal, client, board]
        ▼
  3 builds HTML separados
        │
        │  deploy Cloudflare Pages
        ▼
  3 wikis:  internal.*   client.*   board.*
  • Sync: rclone roda de hora em hora (cron 09/12/17 BRT) + on-push.
  • Build: GitHub Actions roda Quartz 3x em paralelo (matrix), cada um com filtro de audiência.
  • Deploy: cada output vira um projeto Cloudflare Pages distinto.

Gatilhos de ação

A. Mudança material no vault

Quando: você acabou de fazer uma mudança estrutural (nova pasta, renomeação, novo folder note, mudança no publish-contract).

Ação:

  1. Confirmar que o rclone --exclude continua válido (nada crítico novo bloqueado ou coisa privada publicada por erro)
  2. Esperar próximo sync automático (máximo 3h) ou acionar manualmente via GitHub Actions → Run workflow
  3. Verificar o build nos 3 projetos Cloudflare — abrir cada wiki e validar que a nova página apareceu
  4. Checar Network / Console da wiki cliente para garantir que nenhum link aponta para conteúdo [internal] quebrado

B. Arquivo que não deveria publicar está aparecendo

Diagnóstico rápido:

  1. O arquivo tem publish: no frontmatter? Se sim, está com valor correto?
  2. Tem tag #sensivel?
  3. O path está na denylist absoluta do publish-contract §1?
  4. O rclone --exclude em wiki.yml cobre o path?

Ação: adicionar publish: none no frontmatter OU tag #sensivel OU atualizar o rclone exclude. Commit e esperar próximo build.

C. Build Quartz falhou

Primeiro lugar para olhar: GitHub Actions → último run com ❌.

Causas comuns:

SintomaCausa provávelFix
”Module not found”Dependência faltando no Quartz configAtualizar package.json do repo wiki
”Link doesn’t exist” em build-timeLink quebrado no vaultBuscar no vault pelo link e corrigir ou marcar como [[futuro:X]]
”YAML parse error”Frontmatter mal formatado em algum .mdBuscar arquivo recém-editado e validar YAML
Build roda mas deploy Cloudflare falhaToken CF expiradoRegenerar CLOUDFLARE_API_TOKEN no Settings → Secrets
”rclone: config not found”Secret VAULT_REMOTE_CONFIG ausenteRepopular secret com saída de rclone config

D. Conteúdo publicado está desatualizado

Verificar na ordem:

  1. O arquivo foi atualizado no Google Drive? (o vault é a fonte)
  2. O rclone sync trouxe a versão nova? (checar timestamp do último run)
  3. O Quartz build rodou depois do sync?
  4. O Cloudflare Pages deployou o novo build?
  5. Cache do browser/CDN atrapalha? (hard reload / purge CF cache)

Se após todos os passos acima ainda está desatualizado, acionar workflow manualmente no GitHub Actions.

E. Precisa publicar algo com urgência (não pode esperar 3h)

  1. Commit da mudança no vault (via Drive → rclone, ou direto no repo wiki se for emergência)
  2. GitHub Actions → Build e deploy das wikis → Run workflow → branch main
  3. Acompanhar — build + deploy leva ~5-10 min
  4. Verificar URL ao vivo após deploy

Como adicionar uma nova “wiki” (nova audiência)

Procedimento raro — adicionar uma 4ª wiki (ex: fornecedores, auditoria externa).

  1. Decisão registrada em decisoes
  2. Atualizar publish-contract §1-2 com nova audiência
  3. Atualizar audience-scheme
  4. Criar 4º projeto no Cloudflare Pages
  5. Atualizar matrix no wiki.yml
  6. Atualizar secrets no GitHub se nova conta CF necessária
  7. Rodar um dry-run e validar que a audiência só recebe o que deveria

Lições aprendidas / antipadrões

AntipadrãoConsequênciaLição
Commit no repo wiki direto, sem passar pelo vault ObsidianPróximo rclone sobrescreve a ediçãoSempre editar no Obsidian (vault = fonte)
Adicionar publish: [client] sem internalArquivo nunca aparece na interna (onde Anouk valida)Sempre incluir internal na lista
Tag #sensivel aplicada como string sensivel (sem #)Não ativa denylistSempre com #
Editar quartz.config.ts e esquecer de testar preview localBuild production quebraRodar preview.sh antes de commit

Critério de pronto (de uma publicação)

  • Mudança aparece na wiki interna
  • Mudança aparece na wiki cliente (se publish: inclui client)
  • Mudança aparece na wiki board (se publish: inclui board)
  • Links internos funcionam (não há 404 em cross-link válido)
  • Arquivos [internal] NÃO estão acessíveis em client/board (validar com view-source ou abrindo sem login)

Ver também

Visão de gráfico