Repository navigation
ci: label-gated on-demand Vercel previews #830
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
jhoffner
wants to merge
2
commits into
main
Choose a base branch
from
claude/vercel-on-demand-preview-labels-104h7x
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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, andsnapshot-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 👍 / 👎.