Skip to content

Commit 5d1bef6

Browse files
amondnetamondnet
committed
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.
1 parent 2c6dad5 commit 5d1bef6

2 files changed

Lines changed: 221 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: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
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 `vercel:vercel-cli` skill 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: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
94+
env:
95+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
96+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
97+
- run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
98+
env:
99+
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
100+
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
101+
- uses: amondnet/vercel-action@v42
102+
with:
103+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
104+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
105+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
106+
prebuilt: true
107+
```
108+
109+
### Prebuilt — Method 2: let the action build
110+
111+
`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.
112+
113+
```yaml
114+
- uses: amondnet/vercel-action@v42
115+
with:
116+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
117+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
118+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
119+
vercel-build: true
120+
```
121+
122+
### Alias domains with placeholders
123+
124+
`alias-domains` accepts one domain per line and substitutes `{{PR_NUMBER}}` and `{{BRANCH}}`. The domains must already exist on the Vercel project.
125+
126+
```yaml
127+
- uses: amondnet/vercel-action@v42
128+
with:
129+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
130+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
131+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
132+
alias-domains: |
133+
pr-{{PR_NUMBER}}.preview.example.com
134+
{{BRANCH}}.preview.example.com
135+
```
136+
137+
When alias domains are present the `preview-url` output is the first alias rather than the raw deployment URL.
138+
139+
### GitHub Deployments
140+
141+
```yaml
142+
permissions:
143+
contents: read
144+
deployments: write
145+
146+
jobs:
147+
deploy:
148+
runs-on: ubuntu-latest
149+
steps:
150+
- uses: actions/checkout@v4
151+
- uses: amondnet/vercel-action@v42
152+
id: vercel
153+
with:
154+
vercel-token: ${{ secrets.VERCEL_TOKEN }}
155+
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
156+
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
157+
github-token: ${{ secrets.GITHUB_TOKEN }}
158+
github-deployment: true
159+
# Optional override; otherwise auto-derived from vercel-args.
160+
# github-deployment-environment: staging
161+
- run: echo "Deployment id ${{ steps.vercel.outputs.deployment-id }}"
162+
```
163+
164+
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.
165+
166+
## Input reference (essentials)
167+
168+
| Input | Required | Notes |
169+
|---|---|---|
170+
| `vercel-token` | yes | Vercel personal token. |
171+
| `vercel-org-id` | recommended | Required for Vercel CLI 17+. Works for both CLI and API modes — prefer over `scope`. |
172+
| `vercel-project-id` | recommended | Required for Vercel CLI 17+. |
173+
| `vercel-args` | no | Ad-hoc CLI flags (e.g. `--prod`, `--force`). **Mutually exclusive with `experimental-api`**. |
174+
| `working-directory` | no | Run the deploy from a subdirectory. |
175+
| `alias-domains` | no | Multi-line list; supports `{{PR_NUMBER}}` and `{{BRANCH}}`. |
176+
| `prebuilt` | no | Deploy a prebuilt `.vercel/output` directory. **Mutually exclusive with `vercel-build`**. |
177+
| `vercel-build` | no | Run `vercel pull` + `vercel build` inside the action. **Mutually exclusive with `prebuilt`**. |
178+
| `vercel-output-dir` | no | Override the prebuilt output path. Defaults to `{working-directory}/.vercel/output` when `prebuilt: true`. |
179+
| `github-token` | no | Needed for PR/commit comments. |
180+
| `github-comment` | no | `true` (default), `false`, or a custom comment string. |
181+
| `github-deployment` | no | `true` to create a GitHub Deployment. Requires `permissions: deployments: write`. |
182+
| `github-deployment-environment` | no | Override the auto-derived environment name. |
183+
184+
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.
185+
186+
## Outputs
187+
188+
| Output | Set when | Notes |
189+
|---|---|---|
190+
| `preview-url` | always | Raw deployment URL, or the first alias domain if `alias-domains` is set. |
191+
| `preview-name` | always | Deployment name (resolved via `vercel inspect`). |
192+
| `deployment-id` | only when `github-deployment: true` | GitHub Deployment ID — useful for follow-up status updates. |
193+
194+
## Mutual exclusions and gotchas
195+
196+
- `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`).
197+
- `prebuilt` cannot be combined with `vercel-build`. Pick exactly one prebuilt flow.
198+
- `scope` is CLI-mode only. Prefer `vercel-org-id` so the same workflow works in both modes.
199+
- 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.
200+
- 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.
201+
- 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.
202+
203+
## References
204+
205+
- `action.yml` — full input/output contract (source of truth).
206+
- `README.md` — additional examples and a longer changelog.
207+
- https://vercel.com/account/tokens — where to mint the `VERCEL_TOKEN` secret.

0 commit comments

Comments
 (0)