ADR-020: Documentation Preview Deployment

Geliştirme · 0.0.0-dev

Yayın

Doküman: 0.0.0-dev
Uygulama: 0.0.0

Bu sayfa

Uygulama: 0.0.0

Status: Accepted
Date: 2026-08-18
Roadmap task: F1-023
Decision owners: platform, security and documentation maintainers

Context

The documentation application already produces a credential-free static artifact and records its release identity in release.json. Pull requests need a reviewable URL, including contributions from forks, without exposing a hosting credential to code controlled by that pull request.

GitHub Pages’ official deploy-pages preview input is still alpha and not publicly available. Branch-mutating third-party preview actions would add a second content store and shared-branch concurrency. Cloudflare Pages supports Direct Upload preview deployments with immutable deployment URLs and a moving branch alias.

Decision

Cloudflare Pages Direct Upload is the documentation preview provider. It does not own the build: apps/docs/dist/ remains the provider-neutral canonical artifact defined by ADR-019.

The workflow has two privilege domains:

Docs preview build runs on pull_request, checks out the exact head SHA, receives no secret or write permission, builds a source-bound preview and uploads one immutable GitHub artifact.
Docs preview deploy runs on workflow_run from the trusted default branch. It checks out only the trusted verifier, downloads the exact triggering-run artifact, rejects non-static/provider-executable content and deploys it as pr-<number>.

The deploy job never checks out or executes pull-request source. Its Cloudflare token has only Account / Cloudflare Pages / Edit permission and belongs to the protected docs-preview GitHub environment. Action and Wrangler versions are pinned. Preview metadata records the PR ID, exact source Git object, public branch alias and current documentation URL. It remains kind: preview; it is not an immutable historical release.

Provider activation is external and explicit. Until the repository variable and environment secrets exist, preview jobs skip rather than publish against a fabricated account or hostname.

Consequences

Benefits

Fork contributions can be built without credentials and deployed without privileged execution of their source.
Preview URLs are isolated by Cloudflare branch subdomain and default to X-Robots-Tag: noindex.
The deployed artifact identifies the exact PR commit and links back to the current documentation origin.
Local preview generation and validation need no Cloudflare credential.

Costs

Repository owners must create a Direct Upload project, protected environment, one public variable and two environment secrets.
The trusted deploy downloads untrusted static bytes; strict size, file-type, symlink and Cloudflare executable-file checks are therefore mandatory.
Cloudflare project deletion and old deployment retention remain provider operations; F1-023 does not automate destructive cleanup.

Alternatives Considered

GitHub Pages

Official pull-request previews are not publicly available. Rebuilding a shared gh-pages branch per PR would introduce merge races, mutable preview history and extra cleanup code, so it was rejected.

Cloudflare Git Integration

It creates same-repository branch previews but excludes fork pull requests and moves the authoritative build settings into the provider dashboard. Direct Upload keeps the locked repository build and supports privilege separation.

`pull_request_target`

Checking out PR source while holding deployment credentials is an avoidable repository-compromise path. It is prohibited.