Pular para conteúdo

Publishing and Access

1. Objetivo

Este documento define uma forma simples e reproduzivel de publicar a documentacao renderizada do SOT na web sem expor o conteudo ao publico.

O objetivo e permitir que a equipe leia o MkDocs em navegador, mantendo o acesso restrito a pessoas autorizadas.

2. Resultado desejado

Ao final da configuracao:

  • todo merge em develop gera uma nova versao do site
  • o site fica acessivel via web
  • o conteudo nao fica publico
  • o acesso fica restrito a membros autorizados via GitHub e Cloudflare Access

3. Modelo recomendado

O modelo recomendado para o SOT e:

  1. GitHub Actions constroi o MkDocs
  2. GitHub Actions publica os artefatos estaticos no Cloudflare Pages
  3. Cloudflare Access protege o dominio publicado
  4. o login e feito com GitHub
  5. a politica de acesso permite apenas membros da organizacao desejada

4. Porque este modelo foi escolhido

Este modelo ajuda a manter:

  • publicacao automatica
  • independencia de GitHub Pages publico
  • controle de acesso fora do repositorio
  • experiencia simples de leitura para a equipe

Tambem evita misturar essa necessidade com o backlog funcional do produto.

5. Fluxo operacional

flowchart LR
    A[Merge em develop] --> B[GitHub Actions]
    B --> C[Build do MkDocs]
    C --> D[Deploy para Cloudflare Pages]
    D --> E[Cloudflare Access]
    E --> F[Leitura web por usuarios autorizados]

6. Arquitetura de acesso

6.1 Publicacao

O site deve ser publicado como conteudo estatico no Cloudflare Pages.

O deploy recomendado e por Direct Upload via Wrangler a partir do CI.

6.2 Protecao

O site deve ser protegido por Cloudflare Access.

6.3 Identidade

O provedor de identidade recomendado para o primeiro passo e GitHub.

6.4 Regra de autorizacao

A politica recomendada e:

  • permitir apenas usuarios autenticados com GitHub
  • restringir a membros da organizacao GitHub definida pelo time

7. Segredos e variaveis necessarios

No repositorio GitHub, adicionar em Settings > Secrets and variables > Actions:

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID
  • CLOUDFLARE_PAGES_PROJECT

Opcionalmente, em Variables:

  • CLOUDFLARE_PAGES_BRANCH=develop

8. Configuracoes necessarias no Cloudflare

8.1 Pages

Criar um projeto Pages para o fork ou usar um projeto existente preparado para deploy por CI.

8.2 Access

Criar uma aplicacao Access para o dominio do Pages ou para o dominio customizado.

8.3 GitHub como IdP

Configurar GitHub como provedor de identidade no Cloudflare Zero Trust.

8.4 Politica de acesso

Criar uma policy com:

  • Allow
  • usuarios autenticados por GitHub
  • filtro por GitHub organization da organizacao autorizada

9. Sequencia recomendada de implantacao

9.1 Fase 1. Teste no fork

  1. criar projeto Cloudflare Pages para o fork
  2. configurar Cloudflare Access no dominio publicado
  3. configurar GitHub como IdP
  4. restringir acesso a membros da organizacao desejada
  5. adicionar secrets no fork
  6. ativar workflow no fork
  7. testar merge em develop
  8. validar leitura web com um usuario autorizado
  9. validar bloqueio de usuario nao autorizado

Checklist rapido do fork

  • [ ] workflow presente no fork
  • [ ] projeto Pages criado
  • [ ] dominio *.pages.dev identificado
  • [ ] Access habilitado para o dominio
  • [ ] GitHub IdP configurado no Cloudflare
  • [ ] policy restrita a org GitHub configurada
  • [ ] secrets cadastrados no repositório
  • [ ] deploy manual executado com workflow_dispatch
  • [ ] deploy automatico validado via merge em develop
  • [ ] acesso autorizado e nao autorizado testados

9.2 Fase 2. Adocao no repositorio principal

  1. replicar o projeto ou criar projeto Pages do repositorio principal
  2. replicar policy de Access
  3. cadastrar secrets no repositorio principal
  4. habilitar o mesmo workflow no repositorio principal
  5. validar publicacao em develop

10. Validacoes minimas

  • o workflow dispara somente em develop
  • o workflow manual permite teste antecipado quando necessario
  • o site renderiza sem erro
  • usuarios autorizados conseguem acessar
  • usuarios nao autorizados nao conseguem acessar
  • um novo merge substitui o conteudo publicado corretamente

11. Decisoes praticas recomendadas

  • usar develop como branch de publicacao inicial
  • usar deploy por CI com wrangler pages deploy
  • manter o MkDocs buildado a partir de Makefile e mkdocs.yml na raiz
  • manter a protecao de acesso fora do GitHub Pages

12. Fontes oficiais consultadas

  • Cloudflare Pages CI/CD por Wrangler: https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/
  • Cloudflare Pages Direct Upload: https://developers.cloudflare.com/pages/get-started/direct-upload/
  • Cloudflare One GitHub IdP: https://developers.cloudflare.com/cloudflare-one/integrations/identity-providers/github/
  • Cloudflare Access policies: https://developers.cloudflare.com/cloudflare-one/access-controls/policies/