Vercel Staging Workflow

Set up a staging/production workflow for Vercel projects using GitHub Actions and stable URL aliases. Use when asked to create a staging environment, set up...

Security Scan

The skill's files and instructions match its stated purpose (creating a GitHub Action that manages a stable Vercel staging alias); requested secrets and actions are proportional and expected for this task.

Purpose & Capability

Name, description, SKILL.md and the included GitHub Action template all align: they implement a workflow that waits for a Vercel deployment and posts an alias. The required GitHub secrets (VERCEL_TOKEN, VERCEL_PROJECT_ID, optional VERCEL_TEAM_ID) are consistent with Vercel API usage.

Instruction Scope

Instructions stay within the stated domain (Vercel + GitHub Actions). Minor points: SKILL.md suggests running `vercel link --yes` locally to populate .vercel/project.json (this requires the vercel CLI on the developer machine, which is reasonable but not declared as a required binary). The action itself uses curl and jq inside CI (ubuntu-latest runners include these), and it only reads the project file locally as a convenience step.

Install Mechanism

Instruction-only skill with no install spec and no downloads — lowest-risk install surface. It supplies a ready-to-use workflow file that the user copies into their repo.

Credentials

The workflow requires a permanent Vercel API token and project/team IDs — appropriate for calling Vercel's API. These are sensitive credentials; the skill correctly instructs storing them as GitHub secrets. Consider using the least-privilege token scope supported by Vercel, and avoid accidentally using a token that can modify unrelated projects.

Persistence & Privilege

Skill does not request persistent platform privileges (always:false) and does not modify other skills or agent-wide settings. It only provides a repo-scoped GitHub Action the user must add.

Assessment

This skill appears to do what it says: it provides a GitHub Action that polls Vercel for the latest READY deployment and sets a stable staging alias. Before installing, ensure you: (1) create a permanent Vercel API token with the minimum necessary scope and understand which projects it can modify; (2) store the token and IDs as GitHub secrets (do not hardcode them in the workflow); (3) set STAGING_ALIAS to a safe staging subdomain (do not accidentally use your production/custom domain); (4) verify the action's HTTP responses/logs after the first run and consider adding error handling or response checks if you need stricter guarantees; (5) be aware SKILL.md suggests a local step using the vercel CLI to obtain project.json — that step requires the vercel CLI on your machine but is optional if you obtain the projectId from the dashboard. If you need more assurance, test in a non-critical repo first.

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.