Docs Deploy

Workflow reutilizável para build e deploy de sites VitePress no Cloudflare Pages. Inclui gating por content hash para evitar deploys desnecessários quando não há alterações nos fontes de documentação.

Política de publicação

Use este workflow apenas para conteúdo aprovado para publicação. Quando o site contiver guias operacionais sensíveis, a publicação no Cloudflare Pages deve ter uma camada de autenticação antes de ser exposta.

Trigger

on:
  workflow_call:

Chamado via uses: a partir do workflow de deploy de documentação do repositório.

Inputs

Input	Tipo	Padrão	Obrigatório	Descrição
docs-path	string	--	Sim	Caminho do diretório VitePress (ex: docs-site/, docs/)
project-name	string	--	Sim	Nome do projeto no Cloudflare Pages (ex: my-project-docs)
deploy-url	string	--	Sim	URL para verificar o hash do deploy atual (ex: https://my-project-docs.pages.dev)
node-version	string	'22'	Não	Versão do Node.js
build-command	string	'npm run docs:build'	Não	Comando de build a executar dentro do docs-path
force	boolean	false	Não	Força deploy ignorando content hash

Secrets

Secret	Descrição
CLOUDFLARE_API_TOKEN	Token da API Cloudflare com scope de deploy no Pages
CLOUDFLARE_ACCOUNT_ID	ID da conta Cloudflare

Permissions

permissions:
  contents: read
  deployments: write

Job: deploy

Executa em ubuntu-latest:

1. Checkout do código.
2. Computa content hash — calcula SHA-256 de todos os arquivos .md, .ts e .json no diretório de docs (excluindo node_modules, dist e cache).
3. Compara com hash deployado — faz request para <deploy-url>/.content-hash e compara:
   • Se force: true: faz deploy independentemente.
   • Se hashes diferem: faz deploy.
   • Se hashes são iguais: skip do deploy.
4. Setup Node.js com cache de npm.
5. Install e build — npm ci + comando de build configurado.
6. Escreve content hash — salva o hash em .vitepress/dist/.content-hash para comparações futuras.
7. Deploy para Cloudflare Pages — via cloudflare/wrangler-action@v3.

Content Hash Gating

O mecanismo de content hash evita deploys redundantes:

Calcula SHA-256 dos fontes (.md, .ts, .json)
                │
                ▼
Busca hash deployado em <url>/.content-hash
                │
         ┌──────┴──────┐
         │             │
    Diferentes     Iguais
         │             │
         ▼             ▼
    Faz deploy    Skip deploy

O arquivo .content-hash é salvo na raiz do deploy e serve como referência para a próxima execução.

Exemplo de uso

# .github/workflows/docs.yml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs-site/**'

jobs:
  deploy:
    uses: middag-io/.github-private/.github/workflows/docs-deploy.yml@workflows-v1
    with:
      docs-path: docs-site/
      project-name: my-project-docs
      deploy-url: https://my-project-docs.pages.dev
    secrets: inherit

Forçar deploy

jobs:
  deploy:
    uses: middag-io/.github-private/.github/workflows/docs-deploy.yml@workflows-v1
    with:
      docs-path: docs-site/
      project-name: my-project-docs
      deploy-url: https://my-project-docs.pages.dev
      force: true
    secrets: inherit