deploy-docs.yml

name: Deploy docs

# Redeploys the docs site (website/) to production on Prisma Compute when the
# site or the guides it renders change on main. The guides are rendered into
# the bundle at build time, so a docs/guides/ edit needs a redeploy to reach
# the site.
#
# Credentials come in PAIRS — a token and the workspace it belongs to — and the
# two pairs must never be mixed:
#
#   production site : CI_SITE_DEPLOY_TOKEN  + PROD_SITE_WORKSPACE_ID   <- this workflow
#   CI / e2e        : PRISMA_SERVICE_TOKEN  + PRISMA_WORKSPACE_ID      <- e2e-deploy.yml
#
# This workflow originally paired the site's token with PRISMA_WORKSPACE_ID.
# Every run then created a state project (the API puts it in the token's own
# workspace regardless of the workspaceId asked for — PTL-1569), searched for it
# in the workspace it had asked for, found nothing, and deployed a whole new copy
# of the site: five production apps, five green runs.
#
# The CLI reads the token from PRISMA_SERVICE_TOKEN, so the secret is mapped onto
# that name below; the workspace must be the one that token lives in.

on:
  push:
    branches: [main]
    paths:
      - 'website/**'
      - 'docs/guides/**'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:
    inputs:
      reset:
        description:
          'Delete the production project first, then deploy fresh. This is the
          destroy-then-redeploy cutover for state that predates ADR-0034 (the
          old workspace-level state is unreadable, so the deploy fails with
          "app already exists" / "untracked COMPOSER_ key" until the leftover
          resources are removed). The site is briefly down and its generated
          URL changes.'
        type: boolean
        default: false

permissions:
  contents: read

# Fixed group (not per-ref): only one real-cloud deploy of the docs runs at a
# time. cancel-in-progress stays false so a kill mid-deploy can't leave the
# stack half-applied — the deploy is idempotent, an interrupted one is not.
concurrency:
  group: deploy-docs
  cancel-in-progress: false

jobs:
  deploy:
    name: Build and deploy the docs site
    runs-on: ubuntu-latest
    timeout-minutes: 5
    env:
      PRISMA_SERVICE_TOKEN: ${{ secrets.CI_SITE_DEPLOY_TOKEN }}
      PRISMA_WORKSPACE_ID: ${{ vars.PROD_SITE_WORKSPACE_ID }}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      # Renders docs/guides/*.md into the bundle, then builds the entry.
      # `prisma deploy` never builds for you (ADR-0005).
      - name: Build
        run: pnpm turbo run build --filter composer-docs-website
      - name: Reset the production project (destroy-then-redeploy cutover)
        if: github.event_name == 'workflow_dispatch' && inputs.reset
        run: bun scripts/delete-project.ts composer-docs
      # The CLI is invoked directly rather than through the package's `deploy`
      # script, which sources a local .env that does not exist on a runner (the
      # credentials are already in env).
      - name: Deploy to production
        working-directory: website
        run: bun ../node_modules/.bin/prisma deploy --environment production
      # A green deploy is not a serving site (PRO-200), and the URL is a
      # generated service id — so resolve it, print it, and prove it answers.
      - name: Print the URL and smoke-check the site
        working-directory: website
        run: pnpm run verify:deployed