Como um site entra no ar

Um site passa por quatro etapas. Só a última muda o que os visitantes veem.

Rascunho e revisões

O rascunho é o estado atual dos arquivos do site. Cada alteração cria uma revisão: um ID de commit do Git com 40 caracteres, um resumo de uma frase e a autoria (o editor, o assistente, um agente via MCP, a CLI ou a API). Nada é apagado: o histórico lista cada revisão, e você pode comparar duas delas ou restaurar uma anterior como uma nova entrada.

Uma alteração corresponde a uma revisão, independentemente do que ela afeta. Uma chamada que altera três arquivos grava uma única entrada, e uma alteração feita em várias chamadas usa um changeset, que você confirma uma única vez. Um changeset permanece aberto por 10 minutos.

Duas pessoas editando ao mesmo tempo

Ao alterar um arquivo, envie o hash que você leu (expected_hash). Se alguém alterou esse arquivo desde então, a alteração inteira será recusada com 409 conflict, nada será gravado, e um erro REST ou da CLI incluirá a revisão atual:

{
  "error": {
    "type": "conflict_error",
    "code": "conflict",
    "message": "...",
    "details": {
      "reason": "revision_conflict",
      "current_revision": "9f2c...",
      "paths": [
        { "path": "src/content/site/business.json", "expected": "a1b2...", "found": "c3d4..." }
      ]
    }
  }
}

Leia novamente os arquivos listados em paths, aplique sua alteração sobre a versão atual e tente de novo. No MCP, o erro informa que o site mudou desde que a edição foi preparada, sem details; por isso, leia os arquivos novamente por conta própria. Os endpoints de conteúdo leem o hash atual automaticamente, então só haverá conflito se alguém gravar exatamente no mesmo instante.

Builds

Um build compila o rascunho, ou uma revisão que você especificar, em um site estático. Ele é executado em um contêiner isolado, sem rede nem credenciais, e é encerrado após 5 minutos. Um build passa pelos estados queued, building e collecting até chegar a ready, ou termina como failed ou cancelled. Se você iniciar um build de uma revisão que já conta com um build pronto, o build existente será retornado, sem duplicar o processo.

Quando um build falha, error informa o motivo e o log do build mostra a saída do compilador. Corrija os arquivos e execute o build novamente.

Prévia

Uma prévia é um link privado para um build, válido por 7 dias por padrão e por até 30 dias. Qualquer pessoa com o link pode ver esse build, sem precisar de uma conta. O link não concede nenhum outro acesso, nunca é indexado e pode ser revogado. Ele mostra como o site ficaria, por isso, compartilhe-o antes de publicar.

Uma prévia não é um site publicado. Cada página exibe uma pequena faixa “Prévia” (oculta enquanto você edita no app), e é executada em sandbox com a origem null. Os scripts não podem definir cookies, usar o armazenamento do navegador nem iniciar um Worker, e uma API de terceiros que rejeite essa origem impede seu funcionamento. Por isso, um formulário, um banner de cookies ou uma ferramenta do lado do cliente que dependa desses recursos só funcionará depois que o site for publicado. Um aviso do build identifica os recursos usados pelo seu site.

Publicação

A publicação coloca um build no ar em todos os endereços do site, em cerca de um minuto. É a única etapa que altera o site público.

1. Revise. review_publish mostra qual build entraria no ar, se é o rascunho mais recente, o que impede a publicação e um expected_generation.
2. Publique esse build usando o expected_generation que você consultou.

A generation é um contador que aumenta a cada publicação, reversão e retirada do ar. Enviá-la de volta garante que você publique exatamente o estado revisado. Se outra pessoa publicar nesse intervalo, a chamada será recusada com 409 conflict e você precisará revisar novamente.

Um build não pode ser publicado enquanto houver um bloqueio:

Reversão e retirada do ar

Uma reversão volta a disponibilizar o build de uma publicação anterior, sem refazer o build. O rascunho não muda e pode ser mais recente do que a versão que os visitantes veem. Um Site mantém as últimas 50 publicações disponíveis para reversão.

A retirada do ar deixa o site offline: os visitantes veem que não há nenhum site no endereço até que você publique novamente. Nada é excluído.

Publicar, reverter e retirar do ar exige o escopo sites:publish, e somente um administrador do workspace pode executar essas ações. Um agente sem esse escopo pode preparar tudo e pedir ao proprietário que publique.

Exportar e importar

O projeto inteiro é exportado como um arquivo tar que pode ser compilado em qualquer lugar com npm ci && npm run build. A importação de um arquivo substitui o rascunho pelos arquivos contidos nele, em uma única revisão. node_modules, dist, .git e arquivos secretos são ignorados. A importação não executa o build nem publica.