Automate Vercel Deployments With Git Tag Triggers

Aug 4, 2025 by Omar Yusuf 50 views

Trigger Vercel Deployments with Git Tags: A Comprehensive Guide

In this guide, we'll walk through the process of setting up a GitHub Actions workflow that automatically triggers Vercel deployments whenever you create a new tag with a vX.Y.Z structure (e.g., v1.2.3). This approach streamlines your deployment process, ensuring that releases are automatically deployed to Vercel whenever you tag a new version in your repository. This is a crucial practice for maintaining efficient and reliable deployment pipelines. Guys, let's dive deep into how we can achieve this!

Understanding the Need for Tag-Triggered Deployments

Before we jump into the implementation details, let's understand why tag-triggered deployments are beneficial. In software development, tagging is a common practice for marking specific points in the project's history, usually representing releases. When you create a tag (like v1.0.0), you're essentially saying, "This is version 1.0.0 of our software." By linking deployments to tags, you ensure that each release is explicitly marked and easily traceable. This approach brings several advantages:

Version Control: Tags provide a clear and immutable reference to specific releases. When a deployment is triggered by a tag, you know exactly which version of the code is being deployed. This is invaluable for debugging, rollbacks, and maintaining release history.
Automation: Automating deployments through tags reduces manual effort and the risk of human error. Once the workflow is set up, creating a tag is all it takes to trigger a deployment.
Consistency: Tag-triggered deployments ensure consistency across your environments. Each tagged release is deployed in the same way, reducing the chances of discrepancies between environments.
Simplified Rollbacks: If something goes wrong with a new release, you can easily roll back to a previous tag by redeploying that tag. This provides a safety net and reduces downtime.

Tag-triggered deployments are particularly useful for projects that follow semantic versioning (vX.Y.Z) as it provides a structured and predictable way to manage releases. By automating the deployment process based on these tags, you can focus more on development and less on the mechanics of deployment. So, automating this process will save time and reduce potential headaches, making your life as a developer much easier.

Now, let's get into the practical steps of setting up the GitHub Actions workflow. We'll create a workflow file that listens for push events on tags matching the vX.Y.Z pattern and then triggers a Vercel deployment. Here’s how we can do it:

Step 1: Create the Workflow File

First, navigate to your GitHub repository and create a new file in the .github/workflows directory. Let's name this file deploy-on-tag.yml. The .github/workflows directory is where GitHub Actions looks for workflow definitions. This file will contain the YAML configuration that defines our deployment workflow.

Step 2: Define the Workflow

Open the deploy-on-tag.yml file in your editor and add the following YAML configuration. We'll break down each section of the configuration to understand what it does.

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --token ${{
            secrets.VERCEL_TOKEN
        }}

Step 3: Understanding the Workflow Configuration

Let's break down the YAML configuration:

name: Deploy to Vercel on Tag: This line defines the name of the workflow, which will be displayed in the GitHub Actions UI. It's a descriptive name that helps you identify the purpose of the workflow.
on:: This section specifies the events that trigger the workflow. In our case, it's triggered on push events.
- tags:: This further narrows down the trigger to only push events that involve tags.
  - - 'v*.*.*': This is a pattern that matches tags starting with v followed by three sets of digits separated by dots (e.g., v1.0.0, v2.3.4). This pattern ensures that only tags representing version releases trigger the workflow.
jobs:: This section defines the jobs that will run as part of the workflow. A job is a set of steps that execute on a runner environment.
- deploy:: This is the name of the job. You can have multiple jobs in a workflow, but in this case, we have just one.
  - runs-on: ubuntu-latest: This specifies the runner environment where the job will execute. ubuntu-latest is a GitHub-hosted runner with the latest version of Ubuntu.
  - steps:: This section defines the individual steps that will be executed in the job.
    - name: Checkout code: This step checks out your repository's code into the runner environment.
      - uses: actions/checkout@v3: This uses the actions/checkout action, which is a standard action provided by GitHub for checking out code. The @v3 specifies the version of the action to use.
    - name: Install Vercel CLI: This step installs the Vercel CLI globally in the runner environment.
      - run: npm install --global vercel@latest: This command uses npm to install the latest version of the Vercel CLI. The --global flag ensures that the CLI is installed globally and can be accessed in subsequent steps.
    - name: Deploy to Vercel: This step deploys your project to Vercel.
      - run: vercel deploy --prebuilt --token ${{ secrets.VERCEL_TOKEN }}: This command uses the Vercel CLI to deploy the project. The --prebuilt flag tells Vercel to use the prebuilt assets (if any). The --token flag provides the Vercel token for authentication. The ${{ secrets.VERCEL_TOKEN }} syntax accesses the Vercel token stored as a GitHub secret.

Step 4: Configure Vercel Token as a GitHub Secret

To securely authenticate with Vercel, we need to store your Vercel token as a GitHub secret. Here’s how:

Get Your Vercel Token: Go to your Vercel dashboard, navigate to your profile settings, and find the section for tokens. Generate a new token if you don’t have one already. Keep this token handy as you'll need it in the next steps.
Navigate to GitHub Repository Settings: In your GitHub repository, go to Settings > Secrets > Actions.
Add a New Secret: Click on “New repository secret” and add the following:
- Name: VERCEL_TOKEN
- Value: Paste your Vercel token here.
Click “Add secret”: This saves your Vercel token securely in your GitHub repository.

GitHub Secrets provide a secure way to store sensitive information like API keys and tokens, preventing them from being exposed in your codebase.

Step 5: Trigger a Deployment

With the workflow set up and the Vercel token configured, you’re ready to trigger a deployment. Here’s how:

Create a New Tag: In your local repository, create a new tag with the vX.Y.Z format (e.g., v1.0.0).
Push the Tag to GitHub: Push the tag to your GitHub repository using the command:
```
git push origin v1.0.0
```
Replace v1.0.0 with the tag you created.
Verify the Deployment: Go to the “Actions” tab in your GitHub repository. You should see the “Deploy to Vercel on Tag” workflow running. Once the workflow completes successfully, your project will be deployed to Vercel.

While the basic setup we’ve covered is sufficient for many projects, there are several advanced configurations and best practices you might want to consider for more complex scenarios.

1. Environment-Specific Deployments

In some cases, you might want to deploy to different Vercel environments based on the tag. For example, you might want to deploy to a staging environment for tags like v1.0.0-beta and to the production environment for tags like v1.0.0. You can achieve this by modifying the workflow to check the tag and use the appropriate Vercel environment.

Here’s an example of how you can modify the workflow to deploy to different environments:

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'
      - 'v*-*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Determine Environment
        id: env
        run: |
          TAG=${GITHUB_REF#refs/tags/}
          if [[ $TAG == *beta* ]]; then
            echo "::set-output name=environment::staging"
          else
            echo "::set-output name=environment::production"
          fi
        env:
          GITHUB_REF: ${{ github.ref }}

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --env ${{ steps.env.outputs.environment }} --token ${{ secrets.VERCEL_TOKEN }}

In this example, we added a new step called “Determine Environment” that checks the tag and sets the environment output variable. The deployment step then uses this variable to specify the Vercel environment using the --env flag. This is incredibly helpful for managing different deployment environments such as staging and production.

2. Running Tests Before Deployment

It’s a good practice to run tests before deploying to ensure that your code is working correctly. You can add a step to your workflow that runs your project’s tests. If the tests fail, the workflow will stop, preventing a broken release from being deployed.

Here’s how you can add a test step to your workflow:

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --token ${{ secrets.VERCEL_TOKEN }}

In this example, we added steps to install Node.js and project dependencies, and then run the tests using npm test. If the npm test command fails (returns a non-zero exit code), the workflow will stop, and the deployment will be prevented. Running tests is a crucial step to ensure that you're deploying stable and reliable code.

3. Using Vercel Aliases

Vercel aliases allow you to map specific deployments to custom domains or subdomains. This is useful for creating predictable URLs for your deployments. You can use the vercel alias command in your workflow to set up aliases.

Here’s an example of how you can set up aliases:

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Deploy to Vercel
        id: deploy
        run: vercel deploy --prebuilt --token ${{ secrets.VERCEL_TOKEN }}

      - name: Alias to production
        run: vercel alias set ${{ steps.deploy.outputs.result }} your-production-domain.com --token ${{ secrets.VERCEL_TOKEN }}

In this example, we deployed the project to Vercel and then used the vercel alias set command to map the deployment to your-production-domain.com. Make sure to replace your-production-domain.com with your actual domain.

4. Notifying Team Members

It’s helpful to notify team members when a deployment is triggered or completed. You can use various services like Slack, email, or webhooks to send notifications. GitHub Actions provides several actions for sending notifications.

Here’s an example of how you can send a Slack notification using the slackapi/slack-github-action action:

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --token ${{ secrets.VERCEL_TOKEN }}

      - name: Send Slack notification
        uses: slackapi/[email protected]
        with:
          channel-id: '#your-slack-channel'
          slack-token: ${{ secrets.SLACK_TOKEN }}
          status-text: 'New deployment triggered!'

In this example, we used the slackapi/slack-github-action action to send a notification to a Slack channel. You’ll need to set up a Slack app and store the Slack token as a GitHub secret (SLACK_TOKEN). Replace #your-slack-channel with your actual Slack channel ID.

5. Caching Dependencies

To speed up your workflow, you can cache dependencies like Node.js modules. This prevents the workflow from downloading dependencies every time it runs. GitHub Actions provides an action for caching.

Here’s an example of how you can cache Node.js modules:

name: Deploy to Vercel on Tag

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys:
            - ${{ runner.os }}-npm-

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --token ${{ secrets.VERCEL_TOKEN }}

In this example, we used the actions/cache action to cache the ~/.npm directory, which contains the Node.js modules. The key parameter specifies the cache key, which is based on the runner OS and the hash of the package-lock.json file. The restore-keys parameter specifies fallback keys to use if the primary key doesn’t match. Caching dependencies can significantly reduce workflow execution time.

Setting up tag-triggered deployments with GitHub Actions and Vercel is a powerful way to automate your deployment process. By creating a workflow that listens for tags, you can ensure that your releases are consistently and reliably deployed. We’ve covered the basic setup, as well as advanced configurations and best practices to help you optimize your deployment pipeline. This not only saves time but also ensures a smoother release process. Remember, a well-configured deployment pipeline is essential for any modern software project. So go ahead, guys, and implement these strategies to streamline your workflow and focus on what truly matters: building great software!