Skip to content

Can you deploy based on tags/releases on Vercel?

Some engineering teams prefer merging many small updates directly into a main branch. Instead of the traditional model of creating long-living feature branches then merging to main, developers work from a single branch to avoid merge conflicts and introducing build failures. If you’re interested in doing this and deploying to Vercel using tags and releases, this guide will enable you to do just that.

Versioned deployment

If you're using this approach, you don’t want to deploy all commits into the main branch to production. Instead, you’ll want to deploy based on releases or tags as opposed to using Vercel’s auto deployment feature. This is possible using Github Actions alongside Vercel Deploy Hooks. Let’s take a look at how.

  1. Create an unused git branch, go to your Vercel settings, and change your production branch to the unused branch. This is to ensure Vercel isn’t running a new deployment on every commit to your main branch, as we only want to deploy releases or tags to production.
  2. Create a Deploy Hook by navigating to your Vercel Git settings. After specifying a name and your main branch, this will generate a URL that if you send a POST request to, it will trigger a deployment.
  3. Define a GitHub Action with the following syntax, replacing the URL at the end with your generated deploy URL. This will send a POST request to the deploy URL which will trigger a deployment only when a new tag is pushed. You can modify this to trigger on releases as well.
on: push: # Pattern matched against refs/tags tags: - '*' # Push events to every tag not containing / jobs: build: runs-on: ubuntu-latest steps: - run: curl -X POST -d {} https://api.vercel.com/v1/integrations/deploy/sample_deploy_hook

This Github Action will run when a new tag is pushed, triggering a Vercel deployment.

Deploying Hotfixes

If you’re in a scenario where you have a few commits on your main branch that you don’t want to push to production yet, you can deploy a patch or hotfix branch.

For example, adding a hotfix branch name dedicated to deploying hotfixes and another Github Action that only runs when pushes are made to it.

Here’s what you can do:

  1. Create another deploy URL and specify hotfix as the branch name.
  2. Have a separate GitHub Action that only runs on pushes to the hotfix branch. Similarly to the GitHub Action defined above, it will trigger a deploy.
on: push: branches: - hotfix jobs: build: runs-on: ubuntu-latest steps: - run: curl -X POST -d {} https://api.vercel.com/v1/integrations/deploy/hotfix_deploy_hook

Another GitHub Action for the hotfix branch.

Any time you push a hotfix, create a PR to your hotfix branch from your dev branch and Vercel will deploy directly to production using this branch – not use the latest code on main.

Deploy Previews

When deploying based on tags and releases, it’s still possible to take advantage of Vercel’s Preview Deployments. By integrating GitHub Actions with Vercel, you can have Vercel generate Preview Deployments in certain situations.

For example, if your team is deploying on each release, you can create an additional GitHub Action that on each new tag, will create a new branch and generate a deploy preview. You can alternatively have a dev branch that you can push commits to whenever you want a deploy preview.

Couldn't find the guide you need?