Pular para conteúdo

Publicação e manutenção da documentação

O destino oficial é https://flow-docs.ecomsmart.com.br/. Os arquivos ficam no repositório oficial do Flow; MkDocs gera HTML e Cloudflare Pages hospeda o resultado.

flowchart LR
    M[MR revisado de qualquer branch] --> P[Merge na main]
    P --> B[docs_build: validar e gerar site]
    B --> U[docs_publish: upload para Cloudflare oficial]
    U --> S[flow-docs.ecomsmart.com.br]

Os jobs de docs não usam kubeconfig, não fazem build de imagens da aplicação e não executam deploy Kubernetes. Os outros jobs existentes do repositório continuam sujeitos às regras próprias.

1. Criar o projeto na conta oficial

  1. Entrar na conta corporativa correta do Cloudflare e conferir seu Account ID.
  2. Em Workers & Pages, criar uma aplicação Pages pelo fluxo de Direct Upload / upload de assets. A interface pode agrupar essa opção sob criação de aplicação.
  3. Usar o nome sugerido flow-docs-ecomsmart. Se indisponível, escolher outro nome e cadastrar CLOUDFLARE_PAGES_PROJECT com o nome efetivo.
  4. Não conectar o GitLab por integração Git nativa: o GitLab do projeto é self-hosted e esse caminho não é suportado pelo Pages. O upload será feito pelo GitLab CI com Wrangler.
  5. Confirmar que a branch de produção do projeto Pages corresponde à branch padrão do repositório, atualmente main. Não assumir que qualquer upload é classificado como produção; conferir esse campo no projeto, inclusive no primeiro deploy.

Pode ser necessário um primeiro upload para concluir a criação pelo painel. O job docs_build disponibiliza o diretório site/ como artefato; baixar e enviar seus arquivos pelo fluxo de upload é uma alternativa para esse primeiro passo. Não enviar a raiz inteira do repositório.

O projeto e o endereço *.pages.dev antigos podem continuar existindo na conta anterior durante a transição. O nome desse endereço pertence ao projeto antigo; o site oficial terá o domínio próprio, sem depender da transferência daquele subdomínio.

2. Criar a credencial de publicação

No perfil Cloudflare, criar um API Token com permissão Account → Cloudflare Pages → Edit, restrito à conta oficial. Esse token não precisa de permissão para modificar DNS nem recursos Kubernetes. A permissão Pages pode abranger outros projetos da conta; tratar o token conforme esse alcance.

Copiar o token diretamente para o GitLab. Não salvar em Markdown, .env versionado, descrição de MR ou conversa. Account ID não é a senha/token.

3. Cadastrar variáveis no GitLab

Em Settings → CI/CD → Variables:

Variável Tipo/visibilidade Protegida Escopo
CLOUDFLARE_API_TOKEN Variable, Masked and hidden Sim documentation
CLOUDFLARE_ACCOUNT_ID Variable Sim documentation
CLOUDFLARE_PAGES_PROJECT Variable, se o nome for diferente de flow-docs-ecomsmart Sim documentation
ENABLE_DOCS_DEPLOY Variable, valor true Sim *

Desmarcar expansão de referências nas credenciais. A flag de habilitação usa escopo * porque participa da criação dos jobs pelas rules; não depender de variável restrita ao environment para essa decisão.

Manter main protegida. Se houver proteção de environments disponível, restringir documentation aos responsáveis. Tokens de Cloudflare não são necessários no job de build nem nos testes de MR.

4. Primeiro deploy e domínio

  1. Integrar este MR diretamente em main, pelo modo trunk-based temporário.
  2. Conferir docs_build verde. Com a flag habilitada, alterações em docs/configuração na main publicam automaticamente; uma pipeline manual da main oferece docs_publish manual para bootstrap e republicação.
  3. Executar somente os jobs de documentação necessários. Não é preciso executar deploy_production da aplicação para publicar o site.
  4. Conferir no Cloudflare um deploy classificado como Production, na conta e projeto oficiais.
  5. Abrir o projeto Pages → Custom domains → Set up a domain e cadastrar flow-docs.ecomsmart.com.br.
  6. Se a zona ecomsmart.com.br estiver na mesma conta, confirmar o registro DNS sugerido. Se o painel exigir configuração manual, criar CNAME flow-docs apontando para o endereço *.pages.dev do projeto novo.
  7. Aguardar domínio/certificado ativos e validar HTTPS, navegação e busca.

Associar o domínio no Pages antes de criar um CNAME manual. Não apontar flow-docs para o Ingress da aplicação nem alterar os registros de flow e flow-hml.

5. Melhorias e rotas antigas

O site organiza plataforma, jornadas B2B/B2C, serviços, IA, desenvolvimento e operação. A versão atual explica produção em Kubernetes, HML desligada para isolamento e SMTP2GO. Procedimentos antigos de migração são identificados como históricos.

O arquivo docs/_redirects mantém caminhos antigos no novo site direcionados a seus guias equivalentes. Ele não redireciona o domínio antigo: para isso, o dono da conta antiga precisa configurar um redirecionamento ou aviso apontando para o site oficial.

Antes de encerrar a hospedagem antiga, conferir os links compartilhados, comunicar a nova URL e manter um período de transição.

6. Atualização local e revisão

python -m venv .venv-docs
.\.venv-docs\Scripts\python.exe -m pip install -r docs/requirements.txt
.\.venv-docs\Scripts\python.exe -m mkdocs serve --dev-addr 127.0.0.1:8008

Para validar sem iniciar um servidor:

.\.venv-docs\Scripts\python.exe -m mkdocs build --strict

Editar os Markdown em docs/, atualizar nav em mkdocs.yml quando criar páginas e abrir MR para main com título permitido (fix:, feat: ou breaking change:). O prefixo da branch pode ser docs/; ele não define a versão. Quando RELEASE_WORKFLOW=promotion for retomado, voltar ao fluxo via develop.

O build verifica links locais reconhecidos pelo MkDocs e gera pesquisa em português. Diagramas Mermaid são renderizados pelo tema no navegador e também precisam de conferência visual. Dependências diretas e versão de Wrangler estão fixadas; atualizá-las de forma revisada.

7. Falhas e rollback

Sintoma Conferir
docs_build falha Primeira mensagem de link, configuração ou Markdown no build estrito.
docs_publish não aparece Branch padrão/protegida, flag ENABLE_DOCS_DEPLOY, origem e paths da pipeline.
Erro de autenticação Escopo documentation, Account ID, permissão Pages e validade do token.
Projeto não encontrado Nome real na conta oficial e CLOUDFLARE_PAGES_PROJECT. Não criar projeto na conta errada para contornar.
Deploy aparece como Preview Branch de produção do projeto Pages deve corresponder à branch passada pelo job.
Domínio falha Associação em Custom domains, CNAME e emissão de certificado.
Site antigo continua diferente Publicações são independentes; o domínio antigo pode estar na outra conta.

Para voltar a documentação, selecionar um deploy de produção anterior validado no Cloudflare e usar a opção de rollback disponível. Corrigir ou reverter o conteúdo via MR para que a próxima publicação não restaure o erro. Isso não muda tags, imagens, banco ou pods da aplicação.

Referências oficiais