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.
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.
name: Production Tag Deploymentenv: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}on: push: # Pattern matched against refs/tags tags: - '*' # Push events to every tag not containing /jobs: Deploy-Production: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Vercel CLI run: npm install --global vercel@latest - name: Pull Vercel Environment Information run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }} - name: Build Project Artifacts run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }} - name: Deploy Project Artifacts to Vercel run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
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.
name: Hotfix Deploymentenv: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}on: push: branches: - hotfixjobs: Deploy-Production: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Vercel CLI run: npm install --global vercel@latest - name: Pull Vercel Environment Information run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }} - name: Build Project Artifacts run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }} - name: Deploy Project Artifacts to Vercel 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.
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.