Automate Github Page Deployment using Vue3/Vite

In my previous article, I posted about how to publish a website created with Vue/Vite on GitHub Pages. In this follow-up, we'll automate the deployment process using GitHub Actions. This means your webpage will automatically update just by pushing changes to the main branch using git push.

My previous article about setting up GitHub Pages can be found here => Publish a Vue.js 3 / Vite Project on GitHub Pages.

Make sure you've set up your project according to the previous article before proceeding. Once that's done, we can dive into setting up the GitHub Action.

Step 1: Create YML File

First, you'll need to create a specific directory structure in your project's root. This tells GitHub Actions where to find your workflow files.

Create a .github folder in your project's root directory. Inside the .github folder, create another folder named workflows. Finally, inside the workflows folder, create a new file named deploy.yml.

Your folder structure should look like this:

my-project-root/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── src/
├── public/
├── package.json
└── ... (other project files)

This deploy.yml file will contain the instructions for our automated deployment.

Step 2: Set GitHub Secrets

To allow GitHub Actions to push to your repository (specifically to the gh-pages branch), you need to provide secure credentials. We'll use GitHub Secrets for this. You'll need to set up two secrets in your repository's settings:

1. EMAIL: The email address associated with your GitHub account.
2. GH_TOKEN: A GitHub Personal Access Token with repository permissions.

Get GitHub Token

To get a GitHub Personal Access Token (PAT):

1. Go to your GitHub Settings.
2. Navigate to Developer settings > Personal access tokens > Tokens (classic).
3. Click on Generate new token (or Generate new token (classic)).
4. Give your token a descriptive name (e.g., GH_PAGES_DEPLOY).
5. Select the expiration for your token.
6. Under Select scopes, check the repo scope. This will grant the token permissions to access and modify your repositories.
7. Click Generate token.

⚠ Important: Copy the generated token immediately. You won't be able to see it again.

Now, go to your project repository on GitHub:

1. Click on Settings.
2. In the left sidebar, navigate to Secrets and variables > Actions.
3. Click on New repository secret.
4. For the first secret, enter GH_TOKEN as the Name and paste your copied Personal Access Token into the Secret field. Click Add secret.
5. Create another secret. Enter EMAIL as the Name and your GitHub email address as the Secret. Click Add secret.

These secrets will be securely accessible within our GitHub Actions workflow.

Step 3: Write Deploy Command

Now, open your deploy.yml file and add the following configuration. This YAML code defines the workflow for deploying your Vue.js project.

name: Deploy Vue.js Project to GitHub Pages

# Controls when the workflow will run
on:
  # Triggers the workflow on push events but only for the main branch
  push:
    branches:
      - main

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "deploy-project"
  deploy-project:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

    # Sets up Node\.js in the environment
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "latest"

      - name: Install dependencies
        run: npm ci

      - name: build project
        run: npm run build

     # Deploys the built project to the gh\-pages branch
      - name: Deploy to GitHub Pages
        run: |
          cd dist
          git config --global user.email "${{ secrets.EMAIL }}"
          git config --global user.name "${{ github.actor }}"
          git init
          git add -A
          git commit -m 'Automated deployment'
          git push -f https://${{ github.actor }}:${{ secrets.GH_TOKEN }}@github.com/${{ github.repository }}.git master:gh-pages
        shell: bash

Here, we've defined a job named deploy-project that will execute several steps to deploy our application:

1. Checkout code: It checks out our repository's code.
2. Set up Node.js: It installs the specified (or latest) version of Node.js.
3. Install dependencies: It runs npm ci to install our project's dependencies. This is generally preferred in CI environments over npm install as it uses the package-lock.json or npm-shrinkwrap.json for more reproducible builds.
4. Build project: It executes our build script (usually npm run build) to generate the static files in the dist directory.
5. Deploy to GitHub Pages: This is the core deployment step.
   • It navigates into the dist folder (where our built files are).
   • Configures Git with the email (from secrets.EMAIL) and username (the GitHub actor who triggered the action).
   • Initializes a new Git repository in the dist folder.
   • Adds all files, commits them with a message.
   • Force pushes the contents of the dist folder to the gh-pages branch of our repository using the GH_TOKEN secret. The HEAD:gh-pages syntax ensures that the current commit of the dist directory becomes the gh-pages branch.

After committing this deploy.yml file to our main branch and pushing it to GitHub, the Action should trigger automatically. We can monitor its progress under the "Actions" tab of your GitHub repository. Any subsequent pushes to main will also trigger this workflow, automatically rebuilding and redeploying our site!
Check the changes at your gh-pages

https://<username>.github.io/<your-repository-name>/

In my case, as my repository name is Portfolio & my username(check your's at profile setting page) is ishmamabir, my url is:
https://ishmamabir.github.io/Portfolio/

By following these steps, we can automate the deployment process!
Every time changes are pushed into the main branch, they are immediately uploaded to the deploy page.

Apply this to your codebase and enjoy! ✨