Vercel Staging Workflow

Stable staging URLs for Vercel projects via GitHub Actions + Vercel Alias API.

The Problem

Vercel generates random URLs per deployment (myproject-abc123.vercel.app). You want a stable staging URL that always points to the latest main deploy.

The Solution

A GitHub Action that:

1. Triggers on push to main
2. Waits for Vercel's Git-triggered deployment to finish
3. Sets a stable alias: yourproject-staging.vercel.app

Result: Two stable URLs per project:

• yourproject-staging.vercel.app → latest main (auto-updated)
• yourproject.vercel.app → production (manual promote or custom domain)

Setup (per project)

1. Get Vercel Project ID

cd your-project
vercel link --yes
cat .vercel/project.json  # copy projectId

2. Create Permanent API Token

⚠️ Important: Use a permanent token from https://vercel.com/account/tokens — NOT the CLI token (those rotate automatically!).

3. Add GitHub Secrets

In your repo → Settings → Secrets:

• VERCEL_TOKEN — permanent API token
• VERCEL_PROJECT_ID — from step 1
• VERCEL_TEAM_ID — (optional, for team accounts)

4. Add the GitHub Action

Copy references/github-action-template.yml to .github/workflows/staging-alias.yml.

Edit the STAGING_ALIAS variable:

STAGING_ALIAS: "yourproject-staging.vercel.app"

5. Push and verify

git add .github/workflows/staging-alias.yml
git commit -m "ci: add staging alias workflow"
git push

After the action runs, https://yourproject-staging.vercel.app will point to the latest deployment.

Multi-Project Setup

For multiple projects sharing the same token, set VERCEL_TOKEN as an org-level secret and only vary VERCEL_PROJECT_ID per repo.

Production Deploys

Production stays separate — either:

• Use Vercel's "Promote to Production" button
• Set up a production branch that triggers a production alias
• Use custom domains (always point to production)

Key Gotchas

1. CLI tokens rotate — always use permanent API tokens from vercel.com/account/tokens
2. Team accounts need VERCEL_TEAM_ID — find it in Vercel dashboard URL or API
3. Wait time — the action polls for up to 3 minutes for deployment to reach READY
4. Fallback — if exact commit not found, falls back to latest READY deployment

Full Action Template

See references/github-action-template.yml for the complete, commented GitHub Action file ready to copy into your project.