From 5d1bef69823a64e67b13afbb1cd6813795c4f0e0 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Thu, 30 Apr 2026 14:12:07 +0900 Subject: [PATCH 1/2] docs(skill): add use-vercel-action agent skill and README install steps Adds a Claude Code agent skill that documents how to wire amondnet/vercel-action into a GitHub Actions workflow. Consumers install it with: npx skills add amondnet/vercel-action The skill (skills/use-vercel-action/SKILL.md) covers: - Prerequisites checklist (tokens, org/project IDs, vercel.json flag) - Quick-start YAML and five common patterns (production deploy, two prebuilt flows, alias domains, GitHub Deployments) - Essentials input table with every name cross-checked against action.yml - Outputs, mutual-exclusion gotchas, and references README.md gains a new ## Claude Code Skill section between ## Outputs and ## How To Use, advertising the install command and linking to the skill source. --- README.md | 14 ++ skills/use-vercel-action/SKILL.md | 207 ++++++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 skills/use-vercel-action/SKILL.md diff --git a/README.md b/README.md index e7d1710d..2a1a5f26 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,20 @@ The name of deployment name. The GitHub Deployment ID. Only set when `github-deployment` is `true`. Can be used by downstream steps to reference the deployment. +## Claude Code Skill + +This repository ships a [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) agent skill so AI assistants can wire `amondnet/vercel-action` into a workflow correctly — covering required tokens and IDs, CLI vs experimental API mode, prebuilt flows, alias domains, GitHub Deployments, and the action's outputs. + +### Install + +```bash +npx skills add amondnet/vercel-action +``` + +Once installed, prompts like *"deploy to Vercel from GitHub Actions"*, *"post a Vercel preview URL on a PR"*, or *"set up prebuilt Vercel deployments"* surface the skill automatically. + +The skill source lives at [`skills/use-vercel-action/SKILL.md`](./skills/use-vercel-action/SKILL.md) — every input it documents is cross-checked against [`action.yml`](./action.yml). + ## How To Use ### Disable Vercel for GitHub diff --git a/skills/use-vercel-action/SKILL.md b/skills/use-vercel-action/SKILL.md new file mode 100644 index 00000000..6a02488b --- /dev/null +++ b/skills/use-vercel-action/SKILL.md @@ -0,0 +1,207 @@ +--- +name: use-vercel-action +description: Wire `amondnet/vercel-action` into a GitHub Actions workflow to deploy Vercel projects from CI. Use when the user asks to deploy to Vercel from GitHub Actions, add Vercel preview deploys, post a Vercel preview URL on a PR, configure prebuilt Vercel deployments, set up alias domains for previews, create a GitHub Deployment for Vercel, or migrate off Vercel's native GitHub integration. Covers required tokens/IDs, the CLI vs experimental-API modes, prebuilt flows, alias placeholders, deprecated `zeit-*`/`now-*` aliases, and the action's outputs (`preview-url`, `preview-name`, `deployment-id`). +--- + +# use-vercel-action + +This skill teaches an agent how to consume `amondnet/vercel-action` correctly. Inputs and outputs documented here come from `action.yml` in this repo — when in doubt, open `action.yml` for the full surface. + +## When to use + +- Adding `amondnet/vercel-action` to a workflow for the first time. +- Fixing a workflow that already uses the action (input names, mutual exclusions, missing prerequisites). +- Choosing between CLI mode (default), experimental API mode, and the two prebuilt flows. +- Migrating from Vercel's native GitHub integration to action-driven deploys. + +## When NOT to use + +- The user just wants the Vercel CLI locally (no GitHub Actions involved) — refer them to the `vercel:vercel-cli` skill instead. +- The user is happy with Vercel's native GitHub integration and isn't asking for action-based deploys. + +## Mandatory prerequisites + +Consumers consistently miss these. Verify each before writing the workflow: + +1. **Disable Vercel's native auto-deploys** in the project repo, otherwise both Vercel and the action will deploy and you'll get duplicate previews. Add to `vercel.json` (or `vercel.ts`): + ```json + { "git": { "deploymentEnabled": false } } + ``` + Legacy projects may instead use the older `{ "github": { "enabled": false } }` — both are accepted. + +2. **Link the project locally and capture the IDs.** Run `vercel link` once on a developer machine; this writes `.vercel/project.json` with `projectId` and `orgId`. Store those values as GitHub repository secrets: + - `VERCEL_TOKEN` — created at https://vercel.com/account/tokens + - `VERCEL_ORG_ID` — from `.vercel/project.json` + - `VERCEL_PROJECT_ID` — from `.vercel/project.json` + + Do not commit raw IDs into workflow files; reference them via `${{ secrets.* }}`. + +3. **GitHub Deployments need explicit permission.** If you set `github-deployment: true`, the workflow job must declare `permissions: deployments: write` (and usually `contents: read`). Without it the deployment write call fails. + +4. **Action runtime is Node 24.** No consumer-side Node setup is needed for the action itself — the runner provides it. + +## Quick start: preview deploy on every PR + +```yaml +name: Preview Deploy +on: + pull_request: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: amondnet/vercel-action@v42 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + github-token: ${{ secrets.GITHUB_TOKEN }} +``` + +`github-token` is what enables the action to comment the preview URL on the PR. Omit it (or set `github-comment: false`) if you don't want the comment. + +## Common patterns + +### Production deploy on push to main + +```yaml +on: + push: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: amondnet/vercel-action@v42 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + vercel-args: --prod +``` + +### Prebuilt — Method 1: build outside the action + +Build with the Vercel CLI in a prior step, then deploy the prebuilt output. Best when you need to share the build artifact with other steps (tests, smoke checks). + +```yaml +- run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }} + env: + VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} + VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} +- run: vercel build --token=${{ secrets.VERCEL_TOKEN }} + env: + VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} + VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} +- uses: amondnet/vercel-action@v42 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + prebuilt: true +``` + +### Prebuilt — Method 2: let the action build + +`vercel-build: true` runs `vercel pull` + `vercel build` inside the action and then deploys the prebuilt output. Simpler — one step total — but you can't reuse the build artifact elsewhere. + +```yaml +- uses: amondnet/vercel-action@v42 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + vercel-build: true +``` + +### Alias domains with placeholders + +`alias-domains` accepts one domain per line and substitutes `{{PR_NUMBER}}` and `{{BRANCH}}`. The domains must already exist on the Vercel project. + +```yaml +- uses: amondnet/vercel-action@v42 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + alias-domains: | + pr-{{PR_NUMBER}}.preview.example.com + {{BRANCH}}.preview.example.com +``` + +When alias domains are present the `preview-url` output is the first alias rather than the raw deployment URL. + +### GitHub Deployments + +```yaml +permissions: + contents: read + deployments: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: amondnet/vercel-action@v42 + id: vercel + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + github-token: ${{ secrets.GITHUB_TOKEN }} + github-deployment: true + # Optional override; otherwise auto-derived from vercel-args. + # github-deployment-environment: staging + - run: echo "Deployment id ${{ steps.vercel.outputs.deployment-id }}" +``` + +Deployment lifecycle: created `in_progress` before deploy, then transitioned to `success` (with the preview/alias URL as the environment URL) or `failure`. Previous deployments to the same environment are auto-deactivated. + +## Input reference (essentials) + +| Input | Required | Notes | +|---|---|---| +| `vercel-token` | yes | Vercel personal token. | +| `vercel-org-id` | recommended | Required for Vercel CLI 17+. Works for both CLI and API modes — prefer over `scope`. | +| `vercel-project-id` | recommended | Required for Vercel CLI 17+. | +| `vercel-args` | no | Ad-hoc CLI flags (e.g. `--prod`, `--force`). **Mutually exclusive with `experimental-api`**. | +| `working-directory` | no | Run the deploy from a subdirectory. | +| `alias-domains` | no | Multi-line list; supports `{{PR_NUMBER}}` and `{{BRANCH}}`. | +| `prebuilt` | no | Deploy a prebuilt `.vercel/output` directory. **Mutually exclusive with `vercel-build`**. | +| `vercel-build` | no | Run `vercel pull` + `vercel build` inside the action. **Mutually exclusive with `prebuilt`**. | +| `vercel-output-dir` | no | Override the prebuilt output path. Defaults to `{working-directory}/.vercel/output` when `prebuilt: true`. | +| `github-token` | no | Needed for PR/commit comments. | +| `github-comment` | no | `true` (default), `false`, or a custom comment string. | +| `github-deployment` | no | `true` to create a GitHub Deployment. Requires `permissions: deployments: write`. | +| `github-deployment-environment` | no | Override the auto-derived environment name. | + +For the long tail (`target`, `force`, `env`, `build-env`, `regions`, `archive`, `root-directory`, `auto-assign-custom-domains`, `custom-environment`, `public`, `with-cache`, `scope`, `vercel-version`, `vercel-project-name`, `experimental-api`) read `action.yml` — every input there is the source of truth. + +## Outputs + +| Output | Set when | Notes | +|---|---|---| +| `preview-url` | always | Raw deployment URL, or the first alias domain if `alias-domains` is set. | +| `preview-name` | always | Deployment name (resolved via `vercel inspect`). | +| `deployment-id` | only when `github-deployment: true` | GitHub Deployment ID — useful for follow-up status updates. | + +## Mutual exclusions and gotchas + +- `experimental-api: true` cannot be combined with `vercel-args`. The API client uses `@vercel/client`, an internal Vercel package without semver guarantees — keep CLI mode (the default) unless the user explicitly wants the typed inputs (`target`, `regions`, `env`, `build-env`, `public`, `with-cache`, `custom-environment`, `auto-assign-custom-domains`). +- `prebuilt` cannot be combined with `vercel-build`. Pick exactly one prebuilt flow. +- `scope` is CLI-mode only. Prefer `vercel-org-id` so the same workflow works in both modes. +- The auto-detected GitHub Deployment environment is `production` if `vercel-args` contains `--prod` or `--production`, otherwise `preview`. Set `github-deployment-environment` explicitly for `staging` and similar. +- Deprecated input aliases (still accepted, emit deprecation warnings): `zeit-token` → `vercel-token`, `now-args` → `vercel-args`, `now-project-id` → `vercel-project-id`, `now-org-id` → `vercel-org-id`. Always rewrite to the modern names. +- The action sets `VERCEL_TELEMETRY_DISABLED=1` and exports `VERCEL_ORG_ID` / `VERCEL_PROJECT_ID` from the corresponding inputs — don't redeclare them in `env:` for the action step itself. + +## References + +- `action.yml` — full input/output contract (source of truth). +- `README.md` — additional examples and a longer changelog. +- https://vercel.com/account/tokens — where to mint the `VERCEL_TOKEN` secret. From 28ca884adcbe8326abbce4fad57e1f024f3840a4 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Thu, 30 Apr 2026 14:25:57 +0900 Subject: [PATCH 2/2] chore(skill): apply AI code review suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Mark vercel-org-id and vercel-project-id as required to align with README - Add npm install --global vercel@latest step to Prebuilt Method 1 example - Replace vercel:vercel-cli skill reference with vercel.com/docs/cli - Document vercel-build/vercel-args mutual exclusion (enforced at src/config.ts:120) - Clarify GitHub Deployment env auto-detection is mode-dependent (CLI reads vercel-args, API reads target — src/config.ts:74-86) Addresses gemini-code-assist, copilot-pull-request-reviewer, and cubic-dev-ai review threads on PR #367. --- skills/use-vercel-action/SKILL.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/skills/use-vercel-action/SKILL.md b/skills/use-vercel-action/SKILL.md index 6a02488b..f436d8fe 100644 --- a/skills/use-vercel-action/SKILL.md +++ b/skills/use-vercel-action/SKILL.md @@ -16,7 +16,7 @@ This skill teaches an agent how to consume `amondnet/vercel-action` correctly. I ## When NOT to use -- The user just wants the Vercel CLI locally (no GitHub Actions involved) — refer them to the `vercel:vercel-cli` skill instead. +- The user just wants the Vercel CLI locally (no GitHub Actions involved) — refer them to the [official Vercel CLI docs](https://vercel.com/docs/cli) instead. - The user is happy with Vercel's native GitHub integration and isn't asking for action-based deploys. ## Mandatory prerequisites @@ -90,6 +90,7 @@ jobs: Build with the Vercel CLI in a prior step, then deploy the prebuilt output. Best when you need to share the build artifact with other steps (tests, smoke checks). ```yaml +- run: npm install --global vercel@latest - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }} env: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} @@ -106,6 +107,8 @@ Build with the Vercel CLI in a prior step, then deploy the prebuilt output. Best prebuilt: true ``` +The `npm install --global vercel@latest` step is required on a fresh runner — the Vercel CLI is not preinstalled on GitHub-hosted runners. + ### Prebuilt — Method 2: let the action build `vercel-build: true` runs `vercel pull` + `vercel build` inside the action and then deploys the prebuilt output. Simpler — one step total — but you can't reuse the build artifact elsewhere. @@ -168,13 +171,13 @@ Deployment lifecycle: created `in_progress` before deploy, then transitioned to | Input | Required | Notes | |---|---|---| | `vercel-token` | yes | Vercel personal token. | -| `vercel-org-id` | recommended | Required for Vercel CLI 17+. Works for both CLI and API modes — prefer over `scope`. | -| `vercel-project-id` | recommended | Required for Vercel CLI 17+. | -| `vercel-args` | no | Ad-hoc CLI flags (e.g. `--prod`, `--force`). **Mutually exclusive with `experimental-api`**. | +| `vercel-org-id` | yes | Required for Vercel CLI 17+. Works for both CLI and API modes — prefer over `scope`. | +| `vercel-project-id` | yes | Required for Vercel CLI 17+. | +| `vercel-args` | no | Ad-hoc CLI flags (e.g. `--prod`, `--force`). **Mutually exclusive with `experimental-api` and `vercel-build`**. | | `working-directory` | no | Run the deploy from a subdirectory. | | `alias-domains` | no | Multi-line list; supports `{{PR_NUMBER}}` and `{{BRANCH}}`. | | `prebuilt` | no | Deploy a prebuilt `.vercel/output` directory. **Mutually exclusive with `vercel-build`**. | -| `vercel-build` | no | Run `vercel pull` + `vercel build` inside the action. **Mutually exclusive with `prebuilt`**. | +| `vercel-build` | no | Run `vercel pull` + `vercel build` inside the action. **Mutually exclusive with `prebuilt` and `vercel-args`**. | | `vercel-output-dir` | no | Override the prebuilt output path. Defaults to `{working-directory}/.vercel/output` when `prebuilt: true`. | | `github-token` | no | Needed for PR/commit comments. | | `github-comment` | no | `true` (default), `false`, or a custom comment string. | @@ -195,8 +198,9 @@ For the long tail (`target`, `force`, `env`, `build-env`, `regions`, `archive`, - `experimental-api: true` cannot be combined with `vercel-args`. The API client uses `@vercel/client`, an internal Vercel package without semver guarantees — keep CLI mode (the default) unless the user explicitly wants the typed inputs (`target`, `regions`, `env`, `build-env`, `public`, `with-cache`, `custom-environment`, `auto-assign-custom-domains`). - `prebuilt` cannot be combined with `vercel-build`. Pick exactly one prebuilt flow. +- `vercel-build: true` cannot be combined with a non-empty `vercel-args`. The action throws at config-parse time with a clear error — `vercel-build` deploys the locally produced `.vercel/output` via the prebuilt path, while `vercel-args` routes through the CLI path which would ignore that output. - `scope` is CLI-mode only. Prefer `vercel-org-id` so the same workflow works in both modes. -- The auto-detected GitHub Deployment environment is `production` if `vercel-args` contains `--prod` or `--production`, otherwise `preview`. Set `github-deployment-environment` explicitly for `staging` and similar. +- The auto-detected GitHub Deployment environment is mode-dependent. **CLI mode**: `production` if `vercel-args` contains `--prod` or `--production`, otherwise `preview`. **Experimental API mode**: derived from `target` (`production` or `preview`). Set `github-deployment-environment` explicitly for `staging` and similar in either mode. - Deprecated input aliases (still accepted, emit deprecation warnings): `zeit-token` → `vercel-token`, `now-args` → `vercel-args`, `now-project-id` → `vercel-project-id`, `now-org-id` → `vercel-org-id`. Always rewrite to the modern names. - The action sets `VERCEL_TELEMETRY_DISABLED=1` and exports `VERCEL_ORG_ID` / `VERCEL_PROJECT_ID` from the corresponding inputs — don't redeclare them in `env:` for the action step itself.