Skip to content

Commit 9471a56

Browse files
amondnetamondnet
authored
docs(skill): add use-vercel-action agent skill and README install steps (#367)
* 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. * chore(skill): apply AI code review suggestions - 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.
1 parent 2c6dad5 commit 9471a56

2 files changed

Lines changed: 225 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,20 @@ The name of deployment name.
9595

9696
The GitHub Deployment ID. Only set when `github-deployment` is `true`. Can be used by downstream steps to reference the deployment.
9797

98+
## Claude Code Skill
99+
100+
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.
101+
102+
### Install
103+
104+
```bash
105+
npx skills add amondnet/vercel-action
106+
```
107+
108+
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.
109+
110+
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).
111+
98112
## How To Use
99113

100114
### Disable Vercel for GitHub

‎skills/use-vercel-action/SKILL.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
name: use-vercel-action
3+
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`).
4+
---
5+
6+
# use-vercel-action
7+
8+
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.
9+
10+
## When to use
11+
12+
- Adding `amondnet/vercel-action` to a workflow for the first time.
13+
- Fixing a workflow that already uses the action (input names, mutual exclusions, missing prerequisites).
14+
- Choosing between CLI mode (default), experimental API mode, and the two prebuilt flows.
15+
- Migrating from Vercel's native GitHub integration to action-driven deploys.
16+
17+
## When NOT to use
18+
19+
- 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.
20+
- The user is happy with Vercel's native GitHub integration and isn't asking for action-based deploys.
21+
22+
## Mandatory prerequisites
23+
24+
Consumers consistently miss these. Verify each before writing the workflow:
25+
26+
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`):
27+
```json
28+
{ "git": { "deploymentEnabled": false } }
29+
```
30+
Legacy projects may instead use the older `{ "github": { "enabled": false } }` — both are accepted.
31+
32+
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:
33+
- `VERCEL_TOKEN` — created at https://vercel.com/account/tokens
34+
- `VERCEL_ORG_ID` — from `.vercel/project.json`
35+
- `VERCEL_PROJECT_ID` — from `.vercel/project.json`
36+
37+
Do not commit raw IDs into workflow files; reference them via `${{ secrets.* }}`.
38+
39+
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.
40+
41+
4. **Action runtime is Node 24.** No consumer-side Node setup is needed for the action itself — the runner provides it.
42+
43+
## Quick start: preview deploy on every PR
44+
45+
```yaml
46+
name: Preview Deploy
47+
on:
48+
pull_request:
49+
branches: [main]
50+
51+
jobs:
52+
deploy:
53+
runs-on: ubuntu-latest
54+
steps:
55+
- uses: actions/checkout@v4
56+
- uses: amondnet/vercel-action@v42
57+
with:
58+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
59+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
60+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
61+
github-token: ${{ secrets.GITHUB_TOKEN }}
62+
```
63+
64+
`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.
65+
66+
## Common patterns
67+
68+
### Production deploy on push to main
69+
70+
```yaml
71+
on:
72+
push:
73+
branches: [main]
74+
75+
jobs:
76+
deploy:
77+
runs-on: ubuntu-latest
78+
steps:
79+
- uses: actions/checkout@v4
80+
- uses: amondnet/vercel-action@v42
81+
with:
82+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
83+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
84+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
85+
vercel-args: --prod
86+
```
87+
88+
### Prebuilt — Method 1: build outside the action
89+
90+
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).
91+
92+
```yaml
93+
- run: npm install --global vercel@latest
94+
- run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
95+
env:
96+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
97+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
98+
- run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
99+
env:
100+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
101+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
102+
- uses: amondnet/vercel-action@v42
103+
with:
104+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
105+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
106+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
107+
prebuilt: true
108+
```
109+
110+
The `npm install --global vercel@latest` step is required on a fresh runner — the Vercel CLI is not preinstalled on GitHub-hosted runners.
111+
112+
### Prebuilt — Method 2: let the action build
113+
114+
`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.
115+
116+
```yaml
117+
- uses: amondnet/vercel-action@v42
118+
with:
119+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
120+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
121+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
122+
vercel-build: true
123+
```
124+
125+
### Alias domains with placeholders
126+
127+
`alias-domains` accepts one domain per line and substitutes `{{PR_NUMBER}}` and `{{BRANCH}}`. The domains must already exist on the Vercel project.
128+
129+
```yaml
130+
- uses: amondnet/vercel-action@v42
131+
with:
132+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
133+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
134+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
135+
alias-domains: |
136+
pr-{{PR_NUMBER}}.preview.example.com
137+
{{BRANCH}}.preview.example.com
138+
```
139+
140+
When alias domains are present the `preview-url` output is the first alias rather than the raw deployment URL.
141+
142+
### GitHub Deployments
143+
144+
```yaml
145+
permissions:
146+
contents: read
147+
deployments: write
148+
149+
jobs:
150+
deploy:
151+
runs-on: ubuntu-latest
152+
steps:
153+
- uses: actions/checkout@v4
154+
- uses: amondnet/vercel-action@v42
155+
id: vercel
156+
with:
157+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
158+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
159+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
160+
github-token: ${{ secrets.GITHUB_TOKEN }}
161+
github-deployment: true
162+
# Optional override; otherwise auto-derived from vercel-args.
163+
# github-deployment-environment: staging
164+
- run: echo "Deployment id ${{ steps.vercel.outputs.deployment-id }}"
165+
```
166+
167+
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.
168+
169+
## Input reference (essentials)
170+
171+
| Input | Required | Notes |
172+
|---|---|---|
173+
| `vercel-token` | yes | Vercel personal token. |
174+
| `vercel-org-id` | yes | Required for Vercel CLI 17+. Works for both CLI and API modes — prefer over `scope`. |
175+
| `vercel-project-id` | yes | Required for Vercel CLI 17+. |
176+
| `vercel-args` | no | Ad-hoc CLI flags (e.g. `--prod`, `--force`). **Mutually exclusive with `experimental-api` and `vercel-build`**. |
177+
| `working-directory` | no | Run the deploy from a subdirectory. |
178+
| `alias-domains` | no | Multi-line list; supports `{{PR_NUMBER}}` and `{{BRANCH}}`. |
179+
| `prebuilt` | no | Deploy a prebuilt `.vercel/output` directory. **Mutually exclusive with `vercel-build`**. |
180+
| `vercel-build` | no | Run `vercel pull` + `vercel build` inside the action. **Mutually exclusive with `prebuilt` and `vercel-args`**. |
181+
| `vercel-output-dir` | no | Override the prebuilt output path. Defaults to `{working-directory}/.vercel/output` when `prebuilt: true`. |
182+
| `github-token` | no | Needed for PR/commit comments. |
183+
| `github-comment` | no | `true` (default), `false`, or a custom comment string. |
184+
| `github-deployment` | no | `true` to create a GitHub Deployment. Requires `permissions: deployments: write`. |
185+
| `github-deployment-environment` | no | Override the auto-derived environment name. |
186+
187+
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.
188+
189+
## Outputs
190+
191+
| Output | Set when | Notes |
192+
|---|---|---|
193+
| `preview-url` | always | Raw deployment URL, or the first alias domain if `alias-domains` is set. |
194+
| `preview-name` | always | Deployment name (resolved via `vercel inspect`). |
195+
| `deployment-id` | only when `github-deployment: true` | GitHub Deployment ID — useful for follow-up status updates. |
196+
197+
## Mutual exclusions and gotchas
198+
199+
- `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`).
200+
- `prebuilt` cannot be combined with `vercel-build`. Pick exactly one prebuilt flow.
201+
- `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.
202+
- `scope` is CLI-mode only. Prefer `vercel-org-id` so the same workflow works in both modes.
203+
- 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.
204+
- 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.
205+
- 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.
206+
207+
## References
208+
209+
- `action.yml` — full input/output contract (source of truth).
210+
- `README.md` — additional examples and a longer changelog.
211+
- https://vercel.com/account/tokens — where to mint the `VERCEL_TOKEN` secret.

0 commit comments

Comments
 (0)