Step-by-Step Guide to Deploying a Project to Vercel using GitHub Actions for Free

In this guide, I’ll walk you through how to deploy your project to Vercel for free using GitHub Actions, an automation tool provided by GitHub. GitHub Actions allows you to set up continuous integration (CI) and continuous deployment (CD) for your projects, enabling you to deploy code to Vercel automatically every time changes are pushed to a repository.

What are the prerequisites?

• A GitHub account
• A Vercel account (Free tier available)
• A project hosted in a GitHub repository (e.g., React, Next.js, or any other frontend or backend project)
• Basic understanding of GitHub and Vercel

Step 1: Create a Vercel Account

If you don’t have a Vercel account already, follow these steps:

• Visit vercel.com and click Sign Up.
• You can sign up using your GitHub account to make the integration smoother.
• After signing in, you'll be taken to your Vercel dashboard.

Step 2: Connect Your GitHub Repository to Vercel

• In the Vercel dashboard, click the New Project button.
• You’ll be prompted to connect a GitHub repository. Click Import GitHub Repository.
• Authorize Vercel to access your GitHub account if you haven't already.
• From the list of repositories, choose the project you want to deploy to Vercel.
• Vercel will automatically detect the framework you're using (e.g., Next.js, React) and configure the deployment settings.

Step 3: Set Up Environment Variables (if necessary)

If your project requires environment variables, follow these steps:

• After linking the repository, click Settings in your Vercel project dashboard.
• Scroll down to the Environment Variables section.
• Add any environment variables your project needs to run (e.g., API keys, database credentials).

Step 4: Generate a Vercel Token

To use GitHub Actions for deployment, you need a Vercel token:

• In your Vercel dashboard, click on your profile icon in the upper right corner and select Settings.
• Navigate to Tokens under the API Tokens section.
• Click Generate Token, and copy the generated token. You’ll use this in your GitHub repository secrets later.

Step 5: Add Vercel Token to GitHub Secrets

• Navigate to your GitHub repository.
• Click on Settings.
• From the left sidebar, click Secrets and variables and then Actions under the "Security" section.
• Click the New repository secret button.
• Name the secret VERCEL_TOKEN and paste the token you generated from Vercel as the value.
• Save the secret.

Step 6: Set Up GitHub Actions Workflow for Vercel Deployment

Now that GitHub and Vercel are connected, you can configure a GitHub Actions workflow to automate your deployment:

• In the root directory of your project, create a folder named .github if it doesn’t already exist.
• Inside the .github folder, create another folder named workflows.
• In the workflows folder, create a new file called deploy.yml and add the following code:

name: Deploy to Vercel

on:
  push:
    branches:
      - main  # Triggers deployment when code is pushed to the 'main' branch

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

      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'  # Specify the Node.js version you want to use

      - name: Install dependencies
        run: npm install

      - name: Build project
        run: npm run build  # Adjust this if your project uses a different build command

      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}  # Pulls Vercel token from GitHub secrets
        run: npx vercel --prod --token $VERCEL_TOKEN

Explanation of the Workflow:

• on: push – This triggers the workflow when there’s a push to the main branch (you can change this to another branch if necessary).
• jobs – A set of instructions or steps for GitHub Actions to run.
• runs-on: ubuntu-latest – This tells GitHub Actions to use the latest version of Ubuntu for the virtual environment.

steps:

• Checkout repository – This action checks out the project code from the repository.
• Setup Node.js – Installs the Node.js version your project uses.
• Install dependencies – Installs the necessary npm packages.
• Build project – Builds the project using the appropriate command (e.g., npm run build).
• Deploy to Vercel – Uses the Vercel CLI (npx vercel) to deploy the project. The deployment uses the VERCEL_TOKEN secret for authentication.

Step 7: Push the Workflow to GitHub

After saving the deploy.yml file, commit and push it to your GitHub repository:

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow for Vercel deployment"
git push origin main

Once the code is pushed, GitHub Actions will automatically trigger the deployment based on the workflow you set up.

Step 8: Monitor Deployment Progress

• Navigate to the Actions tab in your GitHub repository.
• You’ll see the running workflow, named Deploy to Vercel. Click on it to monitor the progress.
• The workflow should execute each step, and if everything is configured correctly, your project will be deployed to Vercel.

Step 9: Verify the Deployment

i. After a successful deployment, navigate to your Vercel dashboard.
ii. You’ll see the newly deployed project under Deployments.
iii. Visit the provided Vercel URL to ensure everything works as expected.