If your team uses a trunk-based development workflow and you want to deploy using tags and releases, this guide will walk you through the steps to automate deployments via tags instead of branches.
Versioned deployment
Rather than using Vercel's auto-deployment feature to create a production deployment for each commit to the main
branch, this strategy uses GitHub Actions and Vercel CLI to deploy using tags and releases.
- Create a vercel.json file at the root of your project folder to add Git configuration. Set
git.deploymentEnabled
to false which will prevent auto-deployments from commits.. - Then, let’s add the required values from Vercel as secrets in GitHub
- On your local computer or development environment, install the Vercel CLI and run
vercel login
- Inside your project folder, run
vercel link
to create a new Vercel project or link to an existing one - Navigate to the generated
.vercel
folder, and open project.json to find theprojectID
andorgId
- In GitHub, set
VERCEL_PROJECT_ID
to yourprojectID
andVERCEL_ORG_ID
to yourorgID
- Retrieve your Vercel Access Token and set it as the value of
VERCEL_TOKEN
- Define a GitHub Action to kick off a production deployment each time a new tag is pushed.
1name: Production Tag Deployment2env:3 VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}4 VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}5on:6 push:7 # Pattern matched against refs/tags8 tags: 9 - '*' # Push events to every tag not containing /10jobs:11 Deploy-Production:12 runs-on: ubuntu-latest13 steps:14 - uses: actions/checkout@v315 - name: Install Vercel CLI16 run: npm install --global vercel@latest17 - name: Pull Vercel Environment Information18 run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}19 - name: Build Project Artifacts20 run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}21 - name: Deploy Project Artifacts to Vercel22 run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
Deploying Hotfixes
GitHub Actions and Vercel CLI can also be used to create production deployments for patches or hotfixes.
- Create a
hotfix
branch. - Create a separate GitHub Action that only runs on pushes to the
hotfix
branch. This is similar to the GitHub Action defined above, but it will trigger a deployment from thehotfix
branch for each new push to the branch.
1name: Hotfix Deployment2env:3 VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}4 VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}5on:6 push:7 branches:8 - hotfix9jobs:10 Deploy-Production:11 runs-on: ubuntu-latest12 steps:13 - uses: actions/checkout@v314 - name: Install Vercel CLI15 run: npm install --global vercel@latest16 - name: Pull Vercel Environment Information17 run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}18 - name: Build Project Artifacts19 run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}20 - name: Deploy Project Artifacts to Vercel21 run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
Any time you need to push a hotfix, create a PR to your hotfix
branch and Vercel will deploy directly to production using this branch.
Preview Deployments
When deploying based on tags and releases, it’s still possible to take advantage of Preview Deployments with Vercel. By integrating GitHub Actions with Vercel, you can have Vercel generate Preview Deployments.
For example, if your team is deploying on each release, you can create an additional GitHub Action that will create a new branch and generate a preview for each new tag.