vercel-action: deploying to Vercel from GitHub Actions

A deployment action that grew out of a marketplace listing

vercel-action is a GitHub Action that makes a Vercel deployment from a workflow, and the readme gives its own history in the first line. It was formerly the Zeit Now Deployment action, and there is a migration guide for anyone coming from version 2, which is the sort of thing you only find in a project that has been public for a long time and has accumulated users from the old naming.

The platform it targets is described briefly: Vercel is a cloud platform for static sites and serverless functions, aimed at Jamstack websites and web services, with the usual claims of instant deployment and automatic scaling.

What the action does is listed as a checklist. It deploys to Vercel, it can leave a comment on a pull request, it can leave a comment on a commit, it can password protect a deployment with basic auth, it can alias a domain to the deployment, and it can create a GitHub Deployment for the commit.

That last pair, the comments and the GitHub Deployment, is what turns the action from a deploy script into something that fits a team workflow, because a pull request comment with the preview URL and a registered deployment are what a reviewer needs in order to approve a change.

The repository badges also show the continuous integration picture, with separate workflows for deploying the website preview, testing the action, and running the example projects for a static site, for basic auth and for an Angular application.

The input table is where the sharp edges are

The action is configured through a long inputs table, and a few rows deserve a careful read because the defaults are not always the safe choice.

Three inputs are required: vercel-token, which is a token from the Vercel account tokens page, vercel-project-id, and vercel-org-id, the Vercel team id, which the readme also notes is used as the teamId for API deployments.

The project id row carries a warning. It applies to Vercel CLI 17 and later, and the name property in vercel.json is deprecated, which means a workflow written against an older guide will fail in a way that looks like a configuration mistake rather than a deprecation.

vercel-args forwards ad-hoc flags to the Vercel CLI, with the example being --prod --force. It is mutually exclusive with experimental-api, and the same note appears on the scope input, where the readme says to prefer vercel-org-id because that works in both the CLI and the experimental API modes, while scope is only a team slug for the CLI --scope flag.

Two rows are about identity rather than deployment. vercel-project-name is optional, and if it is absent the action uses the vercel inspect command to determine it, which the readme links to two issues about. vercel-version sets the vercel-cli package version, and if it is absent the action uses the one declared in the package.json of the action itself, which is the difference between pinning a CLI and inheriting one.

GitHub Deployments carry an environment that is inferred from your flags

The GitHub integration has three inputs, and the third one is the interesting detail.

github-token is needed if you want to comment on a pull request or a commit, and the readme points at the standard secrets.GITHUB_TOKEN. github-comment defaults to true and can be either a string or a boolean: as a string it leaves a pull request comment with that string, as a boolean it either leaves the default comment or leaves nothing at all. That dual type is convenient, though it also means a workflow that passes an empty string is not the same as one that passes false.

github-deployment defaults to false and creates a GitHub Deployment when set to true. The environment for that deployment is set by github-deployment-environment, and if it is not specified the action detects it: production when vercel-args contains --prod, and preview otherwise.

That inference is a sensible default, because most workflows either pass --prod or they do not, and the environment label on the deployment has to match what the rest of the workflow expects. The case it does not cover is a workflow that promotes a preview to production through some other mechanism, and there the environment has to be set by hand.

The alias-domains input is the one with a template feature. You can assign a domain to the deployment, the domain must already be configured in the project, and you can use the pull request number through {{PR_NUMBER}} and the branch through {{BRANCH}}, which is what makes a per-branch domain possible.

The experimental API path is opt-in and explicitly not the default

There are two ways to reach Vercel in this action, and the readme is careful to keep them apart.

The default is the CLI. The action runs the Vercel CLI in the workflow, which is also why vercel-version and vercel-args exist as inputs at all, and why the project id is tied to CLI 17 and later.

The alternative is experimental-api, which defaults to false and opts in to deployment through @vercel/client. The warning in the input description is specific: the API client relies on an internal Vercel package without semver guarantees and may break across updates. The readme says the CLI is the default and recommended path, and the two options are mutually exclusive.

That is the right way to handle a new code path in an action that people put in their release pipelines. The dependency list backs the story up, with @vercel/client pinned to a specific version, 17.2.65, while the CLI itself is a range, vercel at ^50.0.0, which matches the two different levels of confidence: the CLI is a public interface, the client is not.

The practical advice follows from it. If you need a capability only the API path offers, opt in and pin, and expect to revisit the pin on every Vercel update. If you do not, stay on the CLI path, where an update to the CLI changes behaviour for everybody at once rather than for the people who chose the experimental route.

The repository ships compiled output and five example projects

The repository layout shows a project that has been maintained for a long time, and a few of the entries are useful to know

The action itself is in src, and dist holds the compiled bundle, which is what a JavaScript action has to ship because the runner does not install dependencies for you. The build script shows how it is produced, with ncc bundling the entry point into dist with a source map and a licence file:

"build": "ncc build src/index.ts -o dist --source-map --license licenses.txt",
"test": "vitest run",
"test:integration": "vitest run --project integration"

The test setup is Vitest with named projects, so unit tests and integration tests are separated and each can be run on its own. There is a coverage configuration as well.

The example directory holds five runnable sample projects, a static site, a basic auth example, an Angular application, a Next.js project and a team scope example. Each of those has a workflow in the badge row, which means the examples are exercised by continuous integration rather than being documentation that quietly rots.

The tooling around it is modern and mostly conventional: pnpm as the package manager at 10.15.0, Node 24 as the engine, Husky for the prepare hook, an ESLint flat config using the antfu config, commitlint with the conventional commits preset, release-please for versioning and a Please build file in the .please directory. There is also a vitest configuration, an emulate configuration, a tsconfig, a labels file and a second changelog for the archived history.

A version number in the forties and a repository that still moves

The release history explains the version number.

Version 42.2.0 was published on 2026-04-09, 42.2.1 on 2026-04-28 and 42.3.0 on 2026-04-30, and the package manifest carries the same 42.3.0. A number in the forties for an action that has existed since the Zeit Now era is simply a measure of how often the Vercel CLI and the platform underneath it have changed, because a large part of each release is about compatibility with a new CLI or a new token format.

The last push to the repository was on 2026-07-20, so the tree is being worked on, and the repository is not archived. The changelog machinery deserves a note, because there are two of them: a release-please configuration and manifest for the current line, and a .github_changelog_generator directory with an archived changelog file for everything before it, which is the pattern a project uses when it wants to keep a readable history for old versions without the generator choking on them.

The SonarCloud badges add one more signal, with ratings for maintainability, reliability and security, plus a technical debt index, a bug count and a code smell count. For an action that runs inside other people's release pipelines with a deployment token attached, a visible static analysis dashboard is a reasonable thing to have.

Editorial conclusion

vercel-action fits a team that wants Vercel deployments driven from its own GitHub Actions workflow rather than from the Vercel builder, because the action wraps the CLI, keeps the token, the organisation id and the project id in the workflow file, and reports back through a pull request comment. It is the wrong choice if you need the newest Vercel CLI behaviour on a pinned version, because the CLI version is an input and the project id handling is tied to CLI 17 and later, and it is the wrong choice if you want the API path, because the experimental mode depends on an internal Vercel package with no semver guarantees. Before you adopt it, pin vercel-version deliberately rather than letting it float, set vercel-org-id rather than scope so the same workflow works in both modes, and remember that vercel-args and experimental-api cannot be used together.

Frequently asked questions

Official sources

1. amondnet/vercel-action on GitHub
2. License: MIT
3. Project website
4. README
5. Releases