Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .changeset/preview-deploy-on-demand-labels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
---

Internal: replace Vercel's per-push git auto-deploys with on-demand,
label-gated previews. `git.deploymentEnabled: false` in each project's
`vercel.json` turns off automatic builds; a new `Preview Deploy` GitHub
Action deploys `apps/kitchen-sink`, `apps/docs`, or `packages/ui` (Storybook)
when the matching `preview/*` label is applied to a PR, and posts the
deployment URL as a sticky PR comment. See
`docs/contributing/preview-deployments.md`.
203 changes: 203 additions & 0 deletions .github/workflows/preview-deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
name: Preview Deploy (on-demand)

# On-demand Vercel previews, gated by labels. Nothing deploys automatically on
# push — Vercel's own git deploys are disabled via `git.deploymentEnabled` in
# each app's vercel.json. Apply one of these labels to a PR to opt it in:
#
# preview/kitchen-sink -> apps/kitchen-sink (Next.js)
# preview/docs -> apps/docs (Docusaurus)
# preview/storybook -> packages/ui (Storybook)
#
# Applying a label deploys that target immediately. While the label stays on,
# new commits redeploy that target (the `synchronize` event). Remove the label
# to stop. The deployment URL is posted as a sticky PR comment, one per target.
#
# Setup (secrets): VERCEL_TOKEN, VERCEL_ORG_ID,
# VERCEL_PROJECT_ID_KITCHEN_SINK,
# VERCEL_PROJECT_ID_DOCS,
# VERCEL_PROJECT_ID_STORYBOOK
# See docs/contributing/preview-deployments.md for the full setup guide.

on:
pull_request:
types: [labeled, synchronize]

permissions:
contents: read
pull-requests: write

jobs:
# Compute which targets to deploy for this event:
# - `labeled` -> just the label that was added (if it's a preview/* one)
# - `synchronize` -> every preview/* label currently on the PR
prepare:
runs-on: ubuntu-latest
outputs:
targets: ${{ steps.compute.outputs.targets }}
steps:
- id: compute
uses: actions/github-script@v7
with:
script: |
const MAP = {
'preview/kitchen-sink': { slug: 'kitchen-sink', dir: 'apps/kitchen-sink' },
'preview/docs': { slug: 'docs', dir: 'apps/docs' },
'preview/storybook': { slug: 'storybook', dir: 'packages/ui' },
};
const names = context.payload.action === 'labeled'
? [context.payload.label.name]
: (context.payload.pull_request.labels || []).map(l => l.name);
const targets = [...new Set(names)].filter(n => MAP[n]).map(n => MAP[n]);
core.info(`Deploy targets: ${targets.map(t => t.slug).join(', ') || '(none)'}`);
core.setOutput('targets', JSON.stringify(targets));

deploy:
needs: prepare
if: needs.prepare.outputs.targets != '[]'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
target: ${{ fromJSON(needs.prepare.outputs.targets) }}
# One deploy at a time per PR+target; a newer commit supersedes an
# in-flight build instead of stacking.
concurrency:
group: preview-${{ github.event.pull_request.number }}-${{ matrix.target.slug }}
cancel-in-progress: true
env:
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}

- uses: pnpm/action-setup@v4

- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm

# Vercel reads the project (and its Root Directory) from VERCEL_PROJECT_ID,
# so every command runs from the repo root and Vercel handles the monorepo
# install/build via each app's vercel.json.
# Resolve the project id for this target and check the required secrets
# exist. We report the state (rather than exiting cryptically) so the
# PR always gets a per-target status comment — one findable link per
# label — even when the deploy can't run.
- name: Resolve Vercel project id
id: proj
env:
SLUG: ${{ matrix.target.slug }}
PID_KITCHEN_SINK: ${{ secrets.VERCEL_PROJECT_ID_KITCHEN_SINK }}
PID_DOCS: ${{ secrets.VERCEL_PROJECT_ID_DOCS }}
PID_STORYBOOK: ${{ secrets.VERCEL_PROJECT_ID_STORYBOOK }}
run: |
case "$SLUG" in
kitchen-sink) PID="$PID_KITCHEN_SINK" ;;
docs) PID="$PID_DOCS" ;;
storybook) PID="$PID_STORYBOOK" ;;
*) echo "::error::Unknown target slug '$SLUG'"; exit 1 ;;
esac
missing=""
[ -z "$VERCEL_TOKEN" ] && missing="$missing VERCEL_TOKEN"
[ -z "$VERCEL_ORG_ID" ] && missing="$missing VERCEL_ORG_ID"
[ -z "$PID" ] && missing="$missing VERCEL_PROJECT_ID(for $SLUG)"
missing="${missing# }"
echo "id=$PID" >> "$GITHUB_OUTPUT"
echo "missing=$missing" >> "$GITHUB_OUTPUT"
if [ -n "$missing" ]; then
echo "::warning::Skipping '$SLUG' preview: missing repository secret(s): $missing. See docs/contributing/preview-deployments.md."
fi

- name: Install Vercel CLI
if: steps.proj.outputs.missing == ''
run: npm install --global vercel@latest

- name: Pull Vercel environment
if: steps.proj.outputs.missing == ''
env:
VERCEL_PROJECT_ID: ${{ steps.proj.outputs.id }}
run: vercel pull --yes --environment=preview --token="$VERCEL_TOKEN"

- name: Build project artifacts
if: steps.proj.outputs.missing == ''
env:
VERCEL_PROJECT_ID: ${{ steps.proj.outputs.id }}
run: vercel build --token="$VERCEL_TOKEN"

- name: Deploy prebuilt artifacts
id: deploy
if: steps.proj.outputs.missing == ''
env:
VERCEL_PROJECT_ID: ${{ steps.proj.outputs.id }}
SLUG: ${{ matrix.target.slug }}
run: |
url="$(vercel deploy --prebuilt --token="$VERCEL_TOKEN" | tail -n1)"
echo "url=$url" >> "$GITHUB_OUTPUT"
echo "Deployed $SLUG -> $url"

# One sticky comment per target (keyed by the marker), always posted so
# every label has its own stable, individually-linkable status line —
# deployed URL on success, an actionable pointer otherwise.
- name: Post status to PR
if: always()
uses: actions/github-script@v7
env:
SLUG: ${{ matrix.target.slug }}
URL: ${{ steps.deploy.outputs.url }}
MISSING: ${{ steps.proj.outputs.missing }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
with:
script: |
const { SLUG: slug, URL: url, MISSING: missing, RUN_URL: runUrl } = process.env;
const marker = `<!-- preview-deploy:${slug} -->`;
const sha = context.payload.pull_request.head.sha.slice(0, 7);
let body;
if (url) {
body = [
marker,
`### 🔎 Preview — \`${slug}\``,
'',
`**${url}**`,
'',
`Deployed from \`${sha}\`. Redeploys on new commits while the \`preview/${slug}\` label is applied; remove the label to stop.`,
].join('\n');
} else if (missing) {
body = [
marker,
`### ⚠️ Preview — \`${slug}\` (not configured)`,
'',
`Deploy skipped for \`${sha}\`: missing repository secret(s): \`${missing}\`.`,
'Add them under **Settings → Secrets and variables → Actions** — see `docs/contributing/preview-deployments.md`.',
'',
`[View run](${runUrl})`,
].join('\n');
} else {
body = [
marker,
`### ❌ Preview — \`${slug}\` (build failed)`,
'',
`Deploy failed for \`${sha}\`. [View logs](${runUrl}).`,
].join('\n');
}
const { owner, repo } = context.repo;
const issue_number = context.payload.pull_request.number;
const comments = await github.paginate(github.rest.issues.listComments, {
owner, repo, issue_number, per_page: 100,
});
const existing = comments.find(c => c.body && c.body.includes(marker));
if (existing) {
await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
} else {
await github.rest.issues.createComment({ owner, repo, issue_number, body });
}

# Keep the check red (honestly) when the deploy couldn't run for lack of
# secrets — the sticky comment above says how to fix it.
- name: Fail if not configured
if: steps.proj.outputs.missing != ''
run: |
echo "::error::Preview deploy for '${{ matrix.target.slug }}' was skipped — configure the missing secret(s) noted in the PR comment."
exit 1
3 changes: 3 additions & 0 deletions apps/docs/vercel.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
{
"git": {
"deploymentEnabled": false

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve production deployments when disabling automatic previews

After this merges to the production branch, production updates stop as well as PR previews. Vercel documents that this boolean disables automatic deployments for “all branches”, and the same setting is added to all three projects. I checked .github/workflows/preview-deploy.yml, ci.yml, release.yml, and snapshot-release.yml: the replacement only handles PR events and deploys preview artifacts, with no production deployment path. Keep the production branch enabled through a branch-specific configuration, or add a production deployment replacement before disabling the git integration globally.

Useful? React with 👍 / 👎.

},
"buildCommand": "pnpm build",
"outputDirectory": "build",
"framework": "docusaurus-2",
Expand Down
3 changes: 3 additions & 0 deletions apps/kitchen-sink/vercel.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
{
"git": {
"deploymentEnabled": false
},
"crons": [
{ "path": "/api/cron/static/monday-summary", "schedule": "0 9 * * 1" },
{ "path": "/api/cron/schedule-tick", "schedule": "*/15 * * * *" }
Expand Down
94 changes: 94 additions & 0 deletions docs/contributing/preview-deployments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Preview Deployments (on-demand, label-gated)

Vercel no longer deploys on every push. Previews are opt-in per PR, per target,
via labels. Only PRs you explicitly label ever build.

## Targets

| Label | Source | What it deploys |
| ---------------------- | --------------- | ---------------------- |
| `preview/kitchen-sink` | `apps/kitchen-sink` | The Next.js demo app |
| `preview/docs` | `apps/docs` | The Docusaurus docs site |
| `preview/storybook` | `packages/ui` | The component Storybook |

Each target is a separate Vercel project.

## How to use it

1. Open (or push) a PR.
2. Add one or more of the `preview/*` labels.
3. The [`Preview Deploy`](../../.github/workflows/preview-deploy.yml) workflow
builds that target from your branch and **posts a status as a PR comment** —
one sticky comment per target, updated in place on each redeploy. On success
it shows the deployment URL; if the deploy is skipped (missing secrets) or
fails, the same comment links to the run so each label stays individually
traceable. Each label runs as its own independent deployment — adding a
second label never disturbs the first.
4. While the label stays applied, new commits redeploy that target
automatically (the `synchronize` event). Remove the label to stop.

To force a fresh deploy without pushing a commit, remove the label and re-add it.

## Why it works this way

Vercel's git auto-deploys are disabled at the source, via `git.deploymentEnabled: false`
in each project's `vercel.json` (`apps/kitchen-sink`, `apps/docs`, `packages/ui`).
We deliberately avoid the **Ignored Build Step** mechanism — in practice it
produces stuck "waiting for deployment" / phantom-canceled checks that block
merges. With the git integration off, the only thing that creates a deployment
is the GitHub Action, which builds locally in the runner and uploads prebuilt
artifacts (`vercel build` + `vercel deploy --prebuilt`), so Vercel never runs
its own build.

## One-time setup

### 1. GitHub secrets

Add these under **Settings → Secrets and variables → Actions**:

| Secret | Value |
| ------ | ----- |
| `VERCEL_TOKEN` | A Vercel access token (Vercel → Account Settings → Tokens) |
| `VERCEL_ORG_ID` | Your Vercel org/team ID (shared across all three projects) |
| `VERCEL_PROJECT_ID_KITCHEN_SINK` | Project ID for the kitchen-sink project |
| `VERCEL_PROJECT_ID_DOCS` | Project ID for the docs project |
| `VERCEL_PROJECT_ID_STORYBOOK` | Project ID for the storybook project |

Get the IDs by linking each project locally once and reading `.vercel/project.json`:

```bash
# from the target's root directory, e.g. apps/docs
vercel link # pick the matching Vercel project
cat .vercel/project.json # -> { "orgId": "...", "projectId": "..." }
```

`orgId` is the same for all three (that's `VERCEL_ORG_ID`); each `projectId`
maps to the corresponding `VERCEL_PROJECT_ID_*` secret. Don't commit `.vercel/`.

### 2. Create the labels

Create the three labels in **Issues → Labels** (or they can be added to a PR
from the label picker once they exist):
`preview/kitchen-sink`, `preview/docs`, `preview/storybook`.

### 3. Let Vercel pick up the disabled git integration

After the `vercel.json` change merges, trigger one deployment per project (a
label-gated preview is enough) so Vercel registers `git.deploymentEnabled:
false`. Then confirm the Vercel dashboard no longer creates deployments on push.

### 4. Remove any required Vercel status check

If branch protection on `main` requires a Vercel deployment status check, remove
it — no deployment runs automatically anymore, so that check would block every
merge waiting for a deploy that never starts.

## Changing the behavior

- **Deploy only on the exact commit that was labeled** (no redeploy on later
commits): drop `synchronize` from the workflow's `on.pull_request.types`,
leaving just `[labeled]`. Re-adding the label becomes the only way to redeploy.
- **Add a target**: add an entry to the `MAP` in the `prepare` job, add the
matching `VERCEL_PROJECT_ID_*` secret and the `case` branch in
`Resolve Vercel project id`, and set `git.deploymentEnabled: false` in that
project's `vercel.json`.
3 changes: 3 additions & 0 deletions packages/ui/vercel.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"git": {
"deploymentEnabled": false
},
"buildCommand": "cd ../.. && pnpm install --frozen-lockfile && pnpm packages:build && pnpm --filter @flow-state-dev/ui storybook:build",
"outputDirectory": "storybook-static",
"installCommand": "echo 'install handled in buildCommand'",
Expand Down
Loading