Publicar a documentação

Passo a passo para colocar os dois sites no ar pela primeira vez. Depois disso, publicar é só dar push — os workflows cuidam do resto.

Ao final você terá:

• holy-squat-docs.pages.dev — a vitrine, aberta.
• holy-squat-docs-interno.pages.dev — esta documentação, pedindo e-mail e código antes de abrir.

Não precisa de domínio próprio

O Cloudflare Access consegue proteger a própria URL *.pages.dev de produção. Precisa de um ajuste manual (passo 4.3), mas funciona — domínio próprio é enfeite, não requisito.

1. Conta e projetos

Crie a conta em dash.cloudflare.com se ainda não tiver. Não é preciso adicionar domínio.

São dois projetos, com estes nomes exatos — são os que os workflows referenciam:

Nome do projeto	O que recebe
holy-squat-docs	build de publico/
holy-squat-docs-interno	build de interno/

Pelo terminal (recomendado):

npx wrangler@latest pages project create holy-squat-docs --production-branch main
npx wrangler@latest pages project create holy-squat-docs-interno --production-branch main

A primeira execução abre o navegador para autorizar a conta.

Pelo painel, o caminho é menos óbvio do que parece: Compute → Workers & Pages → Create application cai numa tela de Worker, não de Pages. O Pages está no rodapé dessa tela, no link "Looking to deploy Pages? Get started" → Drag and drop your files. Dê o nome do projeto e arraste qualquer arquivo só para ele nascer; o conteúdo real vem no passo seguinte.

TIP

O painel empurra Workers em vez de Pages, e a interface muda com frequência. Se o caminho de cliques divergir do descrito aqui, use o wrangler — o comando é estável.

2. Primeiro deploy, da sua máquina

Antes de mexer no CI, prove que o caminho funciona:

cd docs-site
npm run build

npx wrangler@latest pages deploy publico/.vitepress/dist \
  --project-name=holy-squat-docs --branch=main

npx wrangler@latest pages deploy interno/.vitepress/dist \
  --project-name=holy-squat-docs-interno --branch=main

A primeira execução abre o navegador para autorizar. Ao final, as duas URLs já respondem — as duas abertas, inclusive a interna. É o passo 4 que fecha a porta.

3. Zero Trust: criar a organização

Zero Trust no menu lateral. Na primeira vez o Cloudflare pede:

1. Team name — identificador da sua organização (ex.: holy-squat). Vira o subdomínio holy-squat.cloudflareaccess.com, onde a tela de login aparece.
2. Plano — escolha Free.
3. Forma de pagamento — sim, ele pede cartão mesmo no plano gratuito. Não há cobrança; o Free cobre até 50 usuários autenticados.

4. Fechar o site interno

4.1 Ligar a política

Workers & Pages → holy-squat-docs-interno → Settings → General → Enable access policy.

Isso cria automaticamente uma aplicação no Access — mas cobrindo *.holy-squat-docs-interno.pages.dev, o curinga, que pega só os preview deployments. A URL de produção continua aberta.

4.2 Definir quem entra

Zero Trust → Access → Applications → abra a aplicação recém-criada → Policies.

• Action: Allow
• Include: Emails → o seu e-mail e o dos convidados

Em métodos de login, deixe o One-time PIN ativo: o convidado recebe um código por e-mail e não precisa ter conta em lugar nenhum.

4.3 Estender para a URL de produção

Este é o passo que quase todo mundo pula, e é ele que fecha a porta de verdade.

Ainda na aplicação, edite o campo de subdomínio e remova o *:

*.holy-squat-docs-interno.pages.dev   →   holy-squat-docs-interno.pages.dev

Se quiser manter os previews protegidos também, crie uma segunda aplicação com o curinga, apontando para a mesma política.

4.4 Conferir

Abra https://holy-squat-docs-interno.pages.dev numa janela anônima. Tem que aparecer a tela pedindo e-mail. Se o conteúdo abrir direto, o 4.3 não pegou.

Faça o mesmo com a URL pública: ela não pode pedir login.

5. Ligar o deploy automático

5.1 Token de API

My Profile → API Tokens → Create Token → Custom token → Get started.

• Permissions: Account · Cloudflare Pages · Edit
• Account Resources: a sua conta

Copie o token — ele só aparece uma vez.

5.2 Account ID

Está na URL do painel: dash.cloudflare.com/<account_id>/.... Também aparece na lateral da página de qualquer projeto.

5.3 Secrets no GitHub

Repositório → Settings → Secrets and variables → Actions → New repository secret:

Nome	Valor
CLOUDFLARE_API_TOKEN	o token do 5.1
CLOUDFLARE_ACCOUNT_ID	o ID do 5.2

5.4 Push

git add docs-site .github/workflows/docs-publico.yml .github/workflows/docs-interno.yml
git commit -m "feat: documentação em VitePress com builds público e interno"
git push

Confira em Actions que os dois workflows passaram. Deste ponto em diante, alteração em docs-site/publico/** republica a vitrine e alteração em docs-site/interno/** republica a documentação — cada uma sem tocar na outra.

6. Domínio próprio (opcional)

Se um dia quiser docs.seudominio.com:

1. Adicione o domínio ao Cloudflare (Add a domain) e aponte os nameservers no registrador.
2. No projeto Pages → Custom domains → Set up a domain.
3. Repita o passo 4 para o novo hostname. Uma política amarrada ao pages.dev não cobre o domínio novo — o site interno reabriria sem aviso.

Armadilhas

• Política que não cobre a produção. O sintoma é o pior possível: tudo parece configurado e o conteúdo está aberto. O teste da janela anônima (4.4) é a única confirmação que vale.
• Domínio novo sem política nova. Mesma coisa, agora quando você achava que já estava resolvido.
• Renomear projeto no Cloudflare quebra os workflows, que referenciam o nome. Se renomear, atualize .github/workflows/docs-*.yml.
• Token com permissão a mais. Cloudflare Pages · Edit basta. Token de conta inteira num workflow é risco desnecessário.