ci: mark site/ as the deprecated docs location

[jwhartley]

Description:

site/ stopped being the source for docs.estuary.dev at cutover on 2026-08-19. Cloudflare Workers now serve that host from estuary/docs, with connector pages coming from estuary/connectors. Both of this repo's site/ workflows kept running as though nothing had changed, and one of them is actively wrong.

docs-ci-previews.yaml posted a sticky comment linking https://docs.estuary.dev/pr-preview/pr-N/. That host is now the Worker, which holds no pr-preview content. Verified 2026-08-20:

/pr-preview/            404
/pr-preview/pr-3382/    404
/pr-preview/pr-3371/    404
/                       200

So every contributor opening a site/ PR got a green check and a dead link, which reads as positive confirmation that their change shipped somewhere. 43 of the 89 open PRs touch site/, and 23 of those touch site/docs/.

site/ itself is not deleted here. It stays until the transition ends (2026-09-30, tentative) so it can serve as the rollback path.

Two changes.

docs-ci-prod.yaml: deprecation header and name: only, no functional change. It still builds site/ and deploys to gh-pages. That branch, plus this repo's Pages config (still cname: docs.estuary.dev, source gh-pages, status: built), is the rollback path for the new site, and this workflow is the only thing keeping it current. It must keep working.

The header names the second cleanup item that lives in no file: the Pages config. It is the rollback path today and a landmine after the transition, because it keeps claiming a hostname Cloudflare serves. Nothing in the repo would otherwise remind whoever deletes site/.

One rename beyond the header: the step Deploy preview is now Deploy to gh-pages (rollback artifact). It never deployed a preview.

docs-ci-previews.yaml: keep the build, drop the deploy, rewrite the comment.

• Kept the build steps. They are the only check that the rollback target still compiles, which is exactly what you want to know before relying on a rollback.
• Dropped rossjrw/pr-preview-action@v1. Its URL is dead, and gh-pages already carries 574 stale pr-preview/ directories (counted 2026-08-20). This stops adding to them.
• Rewrote the sticky comment: site/ is deprecated, here are both new repos, here is what to do, with a separate line for code PRs that only incidentally include a doc file.

Smaller edits, all downstream of dropping the deploy:

• Dropped the closed trigger type and the matching if: github.event.action != 'closed' guards. They existed only so pr-preview-action could tear down a preview directory on close. Without it, a closed run skips every step.
• Dropped BASE_URL: /pr-preview/pr-N. site/docusaurus.config.js:10 reads process.env.BASE_URL || "/", so the build now uses /, which is what the prod workflow already builds with daily.
• Narrowed contents: write to contents: read. Nothing writes any more.
• Renamed the job from deploy-preview to deprecated-site-build-check. The job id is the check name contributors see, and that one was both wrong and reassuring. No required status checks reference it; the estuary-org-default ruleset sets none.

Workflow steps:

Someone opens a PR touching site/. Before: a build, a preview deploy into gh-pages, and a comment linking a URL that 404s.

After: the same build, no deploy, and a comment that says site/ is deprecated, names estuary/docs and estuary/connectors, says the change will not reach the site from here, and says site/ is kept until 2026-09-30 as a rollback path. Nothing about review routing changes; whoever opens the PR still picks their own reviewers.

Maintainers pushing to master see no change at all. site/ still deploys to gh-pages on every site/** push.

Documentation links affected:

None. This changes no doc content, and nothing it builds is on the live site.

Notes for reviewers:

A CODEOWNERS entry was in this PR and has been removed on purpose. An earlier revision added /site/ @jwhartley @aeluce. Dropped, because the estuary-org-default ruleset sets require_code_owner_review: true on the default branch, which makes any CODEOWNERS entry a merge gate rather than a hint. That would have narrowed the approver set for every site/ PR to two people. Approvals should stay open to anyone in the org, and PR authors should choose their own reviewers. The line in the sticky comment claiming site/ PRs need docs-owner review came out with it, since it is no longer true.

Worth knowing that estuary/flow currently has no CODEOWNERS file at all, so that ruleset rule is presently a no-op repo-wide. Adding one anywhere later is a bigger change than it looks.

The slug-derivation logic is removed but not lost. The Compute changed pages step became dead once the preview URL went, but it held careful Docusaurus URL-derivation logic: frontmatter slug, relative slugs resolved against the file's directory, and the category-index convention where PostgreSQL/PostgreSQL.md serves at /PostgreSQL/ and not /PostgreSQL/PostgreSQL/. A naive path-to-URL version of this is wrong, and that mistake has already been caught once in review on the parked docs#7, which needs the same derivation. Recover it with git log -p -- .github/workflows/docs-ci-previews.yaml. The header comment in that file says so too, so it is findable from the file and not only from this PR.

Three things flagged rather than decided here.

1. The rewritten comment does not reach outside contributors. Fork PRs get a read-only GITHUB_TOKEN on pull_request, so the comment step cannot post, and this repo also requires approval before workflows run on fork PRs at all. Confirmed: docs: per-command Docker requirements for flowctl (#2968) #3184 (fork) has no comment and no checks, while docs: name the single MotherDuck metadata table, document splitting it #3382 (internal branch) has the sticky comment. pull_request_target would fix it and is the wrong trade, because it would build untrusted code with a write token. So three of the 23 open site/docs/ PRs (Update mcp-integration.md #3194, docs: per-command Docker requirements for flowctl (#2968) #3184, Update Flow product name references to Estuary in docs homepage #2964) can only be reached by a manual comment. That is tracked outside this PR.

2. clean-exclude: pr-preview/ in docs-ci-prod.yaml is left in place. Removing it would delete the 574 stale directories on the next deploy, which rewrites the rollback artifact. Left alone while rollback is live, with a comment saying so and pointing at cleanup time.

3. Dependabot cannot be stopped the way it looks like it can. There is no .github/dependabot.yml in this repo, so the 20 open /site PRs are Dependabot security updates, which come from a repo setting under Code security rather than a config file. Stopping them means changing that setting or closing the PRs, both outside this PR.

Verification.

This PR touches no site/** path, so it does not trigger the previews workflow itself. Verified on #3385, a throwaway site/docs/ PR based on this branch. Now closed.

• Both files parse as YAML, with the intended name, triggers, permissions, job id and step list.
• The previews workflow runs and passes: 2m24s, under the new job name deprecated-site-build-check.
• The comment posts and reads correctly. It keeps the same sticky header as the old one, so existing site/ PRs will have their dead preview link replaced by this notice on their next push, rather than getting a second comment.
• No new pr-preview/ directory on gh-pages. Count unchanged at 574.
• BASE_URL removal is safe: process.env.BASE_URL || "/".
• /pr-preview/ 404s and / 200s on the live host.
• docs-ci-prod.yaml still produces a gh-pages commit. It triggers on push to master only, so this is checkable after merge, not before. Worth confirming on the first site/** push that lands afterwards.

The #3385 run predates the CODEOWNERS removal. The build and the deploy-absence checks are unaffected by it. The comment body changed by one paragraph since, which is a text-only edit to a block scalar that still parses.

Deliberately not in this PR. Deleting site/docs/, which would conflict all 23 open doc PRs and remove the rollback path. Closing the 20 Dependabot PRs, which is bulk PR closing on a public repo. #3371, which is held open on purpose.

[aeluce]

👍