Vercel and CodeWords: automating around deployments
What belongs in the build and what belongs outside it, deployment notifications people actually read, preview environment hygiene, and correlating releases with what changed.
Aymeric Zhuo11 min read
On this page
Vercel handles deployment well enough that the automation question is not how to deploy. It is everything around deployment: who finds out, what gets recorded, which preview environments are still alive three weeks after the pull request merged, and whether anybody can answer what changed when a metric moves.
The first rule is the same as with any CI system. Anything that is part of building and shipping belongs in the build. Everything that spans deployments, spans projects, or produces something for people belongs outside it.
What we'll cover
- The line between the build and everything else
- What the Vercel API reaches
- Connecting it to CodeWords
- Eight automations worth building
- Deployment notifications people read
- Building it so it survives
- Limits worth knowing about
- What to build first
- Frequently asked questions
The line between the build and everything else
In the build: anything gating the deployment. Tests, type checking, linting, bundle size limits, and checks that should stop a bad deployment reaching production. These belong where they can fail the build.
Outside the build: notifications, records, cleanup, correlation, and anything spanning more than one deployment or more than one project. A build step that posts to chat and updates three external systems works, and it now holds credentials for all of them and runs on every single deployment whether or not any of it was needed.
The practical test: if it should block a deploy, put it in the build. If it should happen after a deploy succeeded, or describes a pattern across deployments, put it outside.
What the Vercel API reaches
Deployments can be listed, read, created, and cancelled, with their state, the commit that produced them, and the build logs.
Projects can be listed and configured, including environment variables and domains.
Environment variables can be read and written per environment, which is how configuration stays in step with whatever system owns the truth about it.
Domains and aliases can be managed, including assigning a deployment to an alias, which is the mechanism behind promotion and rollback.
Logs are available for builds and, depending on plan, for runtime.
Webhooks fire on deployment lifecycle events — created, succeeded, error, canceled — which is what lets automation react rather than poll.
The pattern most automation uses: listen for a deployment event, look up what produced it, and do something with that information somewhere else.
Connecting it to CodeWords
CodeWords connects to more than 3,000 integrations, and the connection is made once and reused.
- Open CodeWords and start a new automation.
- Describe what should happen in plain language to Cody, the automation builder: which project, which event, and what should happen elsewhere.
- Authorize the connection with a Vercel token scoped to the team and, where possible, the project involved.
- Describe the exceptions: a deployment with no associated pull request, a build that failed for infrastructure reasons rather than code, a preview that belongs to a branch that no longer exists.
- Run it in report-only mode first, so you can read what it would have done.
You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.
Eight automations worth building
Deployment records. Every production deployment recorded with its commit, author, timestamp, and what changed since the previous one. This is the automation that makes "what changed?" answerable later, and it costs almost nothing to build.
Analytics annotations. Mark each production deployment on your analytics timeline, so a metric that moves can be correlated with a release rather than investigated from scratch.
Failure notification with context. A failed build reported with the commit, the author, and the relevant portion of the log, sent where that person will see it. The default notification tells you something failed; the useful one tells you what and whose.
Preview environment hygiene. Find previews for branches that were merged or deleted long ago and report them. They accumulate, they occasionally hold data, and nobody tidies them.
Release notes from deployments. Assemble what merged between the last production deployment and this one, grouped and readable, so the release note exists before anyone asks.
Configuration drift detection. Compare environment variables across environments and against whatever holds the truth, and report differences. Configuration drift between preview and production is the cause of a whole category of confusing bugs.
Post-deployment verification. After production deploys, check that key paths respond and respond correctly, and report rather than assume. A successful build is not the same as a working site.
Deployment frequency and failure reporting. How often you ship, how often builds fail, and how long they take, tracked over time rather than felt anecdotally.
Deployment notifications people read
Most deployment notifications are ignored within a month, and the reasons are consistent.
Do not notify on everything. Every preview deployment posting to a channel is noise that trains people to ignore the channel, which costs you the production failure notice later. Production and failures only, by default.
Say what changed, not that something happened. "Deployed abc123 to production" tells nobody anything. The commit subjects since the last deployment tell them whether this is the release they were waiting for.
Name the person. A failed build reported to a channel is everyone's problem and therefore nobody's. Naming the author who triggered it gets it fixed.
Include the link that matters. For a failure, the log. For a success, the deployment. One click, not three.
Group rapid deployments. Five deployments in ten minutes should be one message, not five, or the channel becomes something people mute during active work.
Review what fires monthly. Any notification nobody has acted on in a month should be removed or moved to a digest.
Building it so it survives
Make it safe to run twice. Webhooks retry. A deployment record written twice is untidy; a duplicate notification is how people learn to ignore the channel.
Scope tokens tightly and rotate them. A Vercel token with team-wide access sitting in an automation is a credential that can deploy and change configuration.
Handle the no-pull-request case. Deployments triggered manually or from a direct push have no associated pull request, and an automation assuming one will fail on exactly the deployments that were unusual enough to deserve attention.
Never let an automation promote to production unsupervised unless you have deliberately chosen continuous deployment and built the verification to support it.
Report the outcome. A weekly summary of what shipped is both useful and the thing that tells you the automation is still running.
Limits worth knowing about
Rate limits apply and vary by plan, so an automation walking every deployment across every project needs pacing.
Log retention is limited and varies by plan. An automation that expects to read logs from a deployment last month may find nothing.
Preview deployments can be numerous. Any automation iterating over all deployments should filter by environment and date rather than fetching everything.
Environment variable changes do not affect running deployments. A new deployment is required for them to take effect, which catches automations that update a variable and expect immediate behaviour change.
Tokens carry broad capability. There is no fine-grained permission model comparable to a full cloud provider, so treat a Vercel token as a powerful credential and scope it to the team and project where that option exists.
What to build first
Deployment records with what changed. It is read-only, it takes minutes, and it turns the question "what shipped and when?" from an investigation into a lookup. Everything else in this list is easier once you have that history.
Two habits make the difference. Run it in report-only mode for a cycle and read what it would have said, since the shape of a good notification is not obvious until you see the bad version. And have it report weekly even when nothing interesting happened, because that is what tells you it is still running.
Frequently asked questions
Why not do this with Vercel's built-in integrations?
Use them where they fit — the Slack and GitHub integrations cover basic notification well. Reach outside when you want notifications shaped for your team, when the record needs to go somewhere Vercel does not integrate with, or when the logic spans projects, which the built-in integrations do not.
Should automation deploy to production?
Only if you have deliberately chosen continuous deployment and built the verification to support it. Otherwise the automation should prepare and report, and a person should promote. The distinction matters less for a marketing site than for an application handling money.
How do I clean up old preview deployments?
Report rather than delete, at least at first. Previews for merged or deleted branches are the obvious candidates, and occasionally one is being used by someone for a demo. A weekly report of candidates with an owner named gets them cleaned up without surprises.
Can I detect configuration drift between environments?
Yes, and it is one of the better uses here. Compare environment variable keys across preview, staging, and production and report the differences. A variable present in production and missing from preview is the cause of a surprising share of "works locally" bugs.
How do I correlate a deployment with a metric change?
Write an annotation to your analytics platform on every production deployment. It takes one automation, it costs nothing, and the first time a metric moves and somebody can see that a deployment happened at that moment, it pays for itself.
What happens when a build fails for infrastructure reasons?
Distinguish it from a code failure if you can, because they need different responses and different people. An automation that reports every failure identically will train the team to assume all failures are theirs, which is both wrong and demoralising.
Should preview deployments notify anyone?
Generally no, or only in the pull request itself where the relevant people are already looking. Posting every preview to a shared channel is the most common way these notifications become noise.
How do I handle monorepos with several projects?
Filter by project in the automation rather than reacting to every deployment across the team. A monorepo generates a lot of deployment events, and an automation that treats them all identically will report five deployments when one thing shipped.
Can it roll back automatically on a failed check?
It can promote a previous deployment to the production alias, and whether it should is a judgement. Automatic rollback is reasonable when your post-deployment check is genuinely reliable and the site is stateless. Where a deployment ran migrations, rolling the code back without the data is worse than the original problem.
What should go in a deployment record?
Commit, author, timestamp, environment, and the commit subjects since the previous production deployment. That is enough to answer what changed, which is the question you will actually be asked, and it costs nothing to capture at the time.
Should preview deployments run the same checks as production?
The gating checks, yes, since catching a problem in preview is the entire point. The external automations — notifications, records, annotations — generally should not, or a busy afternoon of preview deployments produces a stream of messages that teaches everyone to ignore the channel.
How do I know a deployment actually worked?
Check the site rather than the build status, because a green build only means it compiled. A post-deployment request against two or three paths that must work, comparing status and a string you expect in the response, catches the class of failure where everything built perfectly and the site is broken.
Should the automation hold production deploy permissions?
Only if it deploys. Most of what is worth building here reads and reports, and a token that can promote to production sitting in a reporting automation is a credential with far more reach than its job requires.