Skip to content
Canonical

docs-site deploy runbook

docs-site deploy runbook

Section titled “docs-site deploy runbook”

Status: Authoring complete; deploy not yet live. Owner: docs track (ID-9). Audience: Liam + future docs operator. Pair with: .github/workflows/docs-site-deploy.yml (the workflow this runbook operates), docs/runbooks/github-environments.md (Environment + secrets pattern), and the ID-9 spec chain under docs/specs/id-9-astro-starlight-docs-foundation/.

§0. Decision context (OQ-68-2)

Section titled “§0. Decision context (OQ-68-2)”

The docs-site is deployed as an access-protected Vercel PREVIEW deploy — NOT public initially. This is Liam’s ruling under OQ-68-2. The workflow and this runbook author the deploy glue; the Vercel project itself is created, linked, and protected by Liam in a follow-up step.

  • Preview, not production. The workflow runs vercel deploy without --prod. Every deploy is a Vercel preview deployment.
  • Access-protected. Deployment Protection (Vercel Authentication or a shared password) is enabled on the Vercel project so the preview URL is private — it cannot be browsed anonymously.
  • Production / custom-domain promotion is DEFERRED. Promoting the docs-site to a public production deployment on a KH-app subdomain is explicitly out of scope for now (OQ-68-2). Do not add a --prod deploy or bind a custom domain until that decision is revisited. The Astro site config still carries the vercel-default-subdomain.vercel.app placeholder (PRODUCT.md Inv-2) — no KH-app subdomain framing is permitted until promotion is approved.

§1. One-time setup (Liam)

Section titled “§1. One-time setup (Liam)”

The workflow is skip-clean until these steps are complete: it builds the site on every run (proving it compiles) but skips the deploy step while the secrets are unset, so the workflow stays green. Complete the steps below to turn the deploy on.

Section titled “1.1 Create and link the Vercel project”

  1. Create a new Vercel project for the docs-site (separate from the Next.js app project). Point it at this repository, with the root directory set to docs-site/.

  2. Vercel auto-detects Astro; the committed docs-site/vercel.json pins the framework (astro), build command (bun install && bun run build), and output directory (dist) so detection cannot drift.

  3. Link the project locally if you want to deploy by hand:

    Terminal window
    cd docs-site
    vercel link

    This writes .vercel/project.json (gitignored) containing the org + project IDs you need for the next step.

1.2 Set the three secrets in the Docs-Preview Environment

Section titled “1.2 Set the three secrets in the Docs-Preview Environment”

The workflow reads its Vercel credentials from a dedicated GitHub Environment named Docs-Preview (capital-first, case-sensitive — GitHub’s environment: matching is case-sensitive per docs/runbooks/github-environments.md §2). Using a separate environment keeps the docs-site deploy credentials isolated from the app’s Production / Staging environments.

Create the environment and set the three secrets:

Terminal window
# Create the environment (or via Settings -> Environments -> New environment).
gh api -X PUT repos/ai-solution-hub/knowledge-hub/environments/Docs-Preview --silent


# Set the three Vercel secrets in that environment scope.
gh secret set VERCEL_TOKEN      --env Docs-Preview --body "<vercel-token>"
gh secret set VERCEL_ORG_ID     --env Docs-Preview --body "<vercel-org-id>"
gh secret set VERCEL_PROJECT_ID --env Docs-Preview --body "<vercel-project-id>"
SecretWhat it isSource
VERCEL_TOKENVercel access token authorising CLI deploys (Sensitive)Vercel account settings -> Tokens
VERCEL_ORG_IDVercel team / org identifier the project belongs to.vercel/project.json after vercel link, or dashboard
VERCEL_PROJECT_IDVercel project identifier for the docs-site project.vercel/project.json after vercel link, or dashboard

All three are typed as secrets (not variables): the token is a credential, and the IDs are scoped to the deploy flow with no need to surface in logs.

Never commit any of these values. They live only in the Docs-Preview GitHub Environment (and, for local CLI work, in the gitignored docs-site/.vercel/). No token or ID is ever written into the repository.

The workflow’s Determine deploy configuration step probes for VERCEL_TOKEN presence and sets the deploy step’s if: gate. Once VERCEL_TOKEN is set, the deploy runs; until then it logs “docs-site deploy not yet configured — skipping” and the workflow succeeds.

1.3 Enable Deployment Protection (makes previews private)

Section titled “1.3 Enable Deployment Protection (makes previews private)”

In the Vercel project: Settings -> Deployment Protection -> enable Vercel Authentication (recommended — restricts previews to your Vercel team members) or set a Password for shared access. This is what makes the preview URL access-protected per OQ-68-2. Without it, preview URLs are guessable and effectively public — do not skip this step.

§2. Build pipeline

Section titled “§2. Build pipeline”

The deploy is driven by .github/workflows/docs-site-deploy.yml. Triggers:

  • workflow_dispatch — manual run (deploy or build check).
  • push on main / staging touching docs-site/**, docs/**, or the workflow file itself.

Pipeline stages (all run inside docs-site/):

  1. Checkout + set up Bun.
  2. Install — bun install --frozen-lockfile.
  3. Sync content — bun scripts/sync-content.ts mirrors the tracked docs/ corpus into docs-site/src/content/docs/ (PRODUCT.md Inv-19).
  4. Build — bun run build, which chains sync -> check-broken-links -> check-token-parity -> astro check -> astro build, emitting the static site to dist/. This stage runs on every workflow run, even when the deploy step is skipped, so a broken build is caught regardless of deploy configuration.
  5. Deploy (gated) — when the Docs-Preview secrets are present, installs the Vercel CLI and runs vercel pull + vercel deploy (PREVIEW, no --prod). The resulting URL is written to the job summary.

Build-green precondition (separate follow-up). A successful deploy is blocked on the docs-site build going green. The synced corpus can carry pre-existing content debt (broken internal links tracked under the Inv-6 link-rewriter follow-up) that can fail bun run build at the check-broken-links step. That debt is out of scope for the deploy glue — it is remediated by the docs-site build-green follow-up, which is distinct from the Vercel-project-creation steps in §1. The workflow and runbook are valid regardless; the deploy step simply will not produce a dist/ for Vercel until the corpus build passes.

Note (S292): the check-ai-invisibility guard was removed from the build chain — the AI-invisibility principle (PRODUCT.md Inv-23) governs user-facing app UI copy, not the internal docs corpus, which must quote the forbidden phrases to define the policy. ID-9 PRODUCT.md Inv-23 / TECH.md §2.10 still describe the retired guard and should be reconciled.

§3. Capturing the preview URL for the {9.24} Playwright E2E

Section titled “§3. Capturing the preview URL for the {9.24} Playwright E2E”

The deploy step emits the Vercel preview URL to the GitHub job summary under DOCS_SITE_URL. To run the {9.24} Playwright E2E against the deployed preview:

  1. Open the docs-site deploy workflow run -> the job summary shows the DOCS_SITE_URL value.

  2. Export it and run the E2E:

    Terminal window
    cd docs-site
    DOCS_SITE_URL="<url-from-job-summary>" bun run test:e2e

Because the preview is access-protected (§1.3), the E2E either needs a Vercel protection-bypass token (Vercel project -> Deployment Protection -> Protection Bypass for Automation) supplied as a header / query param, or must run against a deploy made before protection is enabled. Wiring the bypass token into the E2E is part of {9.24}, not this deploy-glue task.

§4. Rollback

Section titled “§4. Rollback”

Vercel retains every preview deployment; rollback is selecting a known-good prior deployment.

  • Via dashboard: Vercel project -> Deployments -> pick the last good preview -> … -> Promote / Redeploy (preview scope). The previous deployment URL keeps working — no destructive action is needed.

  • Via CLI:

    Terminal window
    cd docs-site
    vercel ls            # list recent deployments
    vercel redeploy <deployment-url-or-id> --token="$VERCEL_TOKEN"

  • Disable the workflow: if a bad deploy must be stopped at source, revert the offending commit on main / staging (the path-filtered trigger only fires on docs-site/**, docs/**, or the workflow file) or temporarily remove the VERCEL_TOKEN secret from the Docs-Preview environment — the workflow then reverts to build-only (skip-clean) and stops deploying.

No production deployment or custom domain is involved, so rollback never affects a public surface.

§5. Cross-references

Section titled “§5. Cross-references”
  • .github/workflows/docs-site-deploy.yml — the workflow this runbook operates.
  • docs/runbooks/github-environments.md — canonical GitHub Environment + secrets pattern (case-sensitive environment: matching, secrets vs vars).
  • docs/specs/id-9-astro-starlight-docs-foundation/ — ID-9 spec chain (PRODUCT.md Inv-2 Vercel default subdomain placeholder, Inv-19 build-time sync, Inv-21 builds from main).
  • docs-site/vercel.json — framework / build / output pinning for the Vercel project.
  • docs-site/package.json — the build script chain (sync + guards + astro build).