DEV Community

Cover image for Build, Deploy, and Host Your Vite App on GitHub Pages with GitHub Actions CI/CD
Bruce Simiyu
Bruce Simiyu

Posted on

Build, Deploy, and Host Your Vite App on GitHub Pages with GitHub Actions CI/CD


Build, Deploy, and Host Your Vite App on GitHub Pages with GitHub Actions CI/CD


GitHub Actions is a powerful, flexible, and user-friendly CI/CD platform that allows you to automate your build, test, and deployment pipeline from idea to production. With GitHub Actions, you can define, create and share actions to perform a job without leaving the GitHub environment. An example of a possible job you’d like done includes combining actions in a custom workflow for CI/CD.

GitHub Actions allows you to run a workflow on any GitHub events like issue creation, new release, or push. Whether you want to deploy on a web service, build a container, or automate new users to your open-source projects, an action is available for that. GitHub offers Linux, macOS, and Windows virtual machines to run your workflows. However, you can use your self-hosted runners in cloud infrastructure or your own data center.
GitHub Actions support your language of choice such as .NET, Rust, Go, PHP, Ruby, Java, Python, and Node.js. I will take you through building a CI/CD workflow for a React project. We will use Vite to scaffold the development environment. Vite is a build tool that aims at offering a leaner and faster development experience for modern-day web projects. To host our app directly from our repository, we will use GitHub Pages. To learn more about GitHub pages, visit GitHub Pages Official docs.


  • Node v.16+: Our yaml file is configured to run on machines that have node-version 16. Please update your machine to the latest version.
  • Some knowledge on running Git commands on Git Bash.
  • A development environment; I will use Visual Studio Code.
  • A GitHub Account

We are going to do the following:

  • Scaffold a new React application with Vite and create its empty repository in GitHub
  • Set the base of vite.config.js to the name of our repository
  • Create the .github/workflows/deploy.yaml file and add our custom workflows
  • Push the app to GitHub, configure GitHub Pages and activate your workflow
  • Ensure deployment success.

Let’s scaffold a new React application locally and create an empty GitHub repository remotely

The best method to scaffold a React project is by using Vite. Use any of the commands below depending on your package manager:

  • With NPM: npm create vite@latest my-ghactions-app --template react
  • With Yarn: yarn create vite my-ghactions-app --template react
  • with PNPM: pnpm create vite my-ghactions-app --template react

Image description

This command prompts you to select a framework and a variant of your choice. For our project, we will use React as our framework and JavaScript as our variant.

Now that we have our Vite application up and running, let’s create a new repository in GitHub.

Before we push our Vite application to the GitHub repository, let’s first;

  • Add the base in vite.config.js file. Set its name to that of our currently empty GitHub repository.
  • Create the .github/workflows directory in the root folder. This is where we create our deploy.yml file.

Working with workflows: The .github/workflows/deploy.yaml file

You can configure a GitHub Actions workflow that will be triggered when an event has occurred in your repository, such as when a pull request is opened or when a new issue is created. Your workflow comprises one or more jobs which can run in parallel or in a sequential order. Each job runs inside its own virtual machine runner, or inside a container, and has one or multiple steps that either run a script you define or an action (a reusable extension that simplifies your workflow.)


A workflow is a configurable automated process that is going to run a single or multiple jobs. To define workflows, we use a YAML file that is checked into your repository and will run when an event in your repository triggers them.

The YAML files also run at a defined schedule or when manually triggered.

We define workflows in the .github/workflows directory in a repository. A repository can have multiple workflows each of which is set to perform a different set of tasks.

For instance, you can have a workflow that builds and tests pull requests, another workflow that deploys your application every time there is a new release made, and another one that adds a label every time a new issue has been created.

Workflow Basics

The following are basic components a workflow must contain;

  • One or more event to trigger the workflow

  • Single or multiple jobs, each of which is going to execute on a runner machine and run a series of one or more steps.

  • Each step can either run an action, which is a reusable extension that simplifies your workflow, or run a script you define.

Triggering a Workflow

Those events that cause a workflow to run are known as workflow triggers. These events can be:

  • Events that occur in the workflows of your repository.
  • Events that occur outside GitHub triggering a repository_dispatch event on GitHub
  • Scheduled times
  • Manual

For instance, you could configure your workflow to run when a new release has been created, when a new issue is opened, or when a push has been made to the default branch of your repository.

In our .github/workflows/deploy.yaml file, copy and paste this code.
While copying this file, check on how the spacing of elements is done. Failure might result in a dormant workflow.
Copy and paste this file to your .github/workflows/deploy.yaml without adding any customs.

name: Deploy

      - main

    name: Build
    runs-on: ubuntu-latest

      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v1
          node-version: 16

      - name: Install dependencies
        uses: bahmutov/npm-install@v1

      - name: Build project
        run: npm run build

      - name: Upload production-ready build files
        uses: actions/upload-artifact@v2
          name: production-files
          path: ./dist

    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

      - name: Download artifact
        uses: actions/download-artifact@v2
          name: production-files
          path: ./dist

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist 

Enter fullscreen mode Exit fullscreen mode

We have everything required to run our workflows now. Push the Vite app to GitHub and activate your workflow.

Upon pushing your Vite app to GitHub, wait as the build and deploy checks are running. Running checks are indicated by a yellow spinning dot. A green checkmark represents successfully run checks while a red one indicates failed checks.

We expect a red mark that indicates failing checks because on pushing the code to the repository, the build process will run successfully but the deploy check will fail because we have not yet instructed it where we are deploying from.

Image description

Workflow permissions and Deploying to GitHub Pages

Navigate to “code and automation” in the repository settings. Here, we will click Actions to prompt a dropdown. Clicking “General” allows us to set our workflow permissions to “read and write permissions”. Save the changes and rerun the failed workflows.

Our failed deploy workflow rerun successfully and popped green checks indicating that our app is ready.
Once the build and deploy steps run successfully, we can find our site’s file in the gh-pages.
To see our app, we are supposed to build our GitHub Pages site from the gh-pages branch where our files are located.

Publishing your app might take a moment so don’t be in panic once you cannot see your site live.

Image description

The default domain of a site you’d like to publish to GitHub is, where is your GitHub username.
For instance, if my GitHub username is Brucedevnairobi, my published site’s domain name would be However, you can create a custom domain name that allows you to serve your site from a domain other than

Other web hosting environments you would use for your applications rather than GitHub Pages include Netlify, GitLab Pages, Vercel, Heroku, Firebase Hosting, Amazon S3, Amazon EC2, among many more.

You are all set

Any changes you make locally will be sent to production upon pushing your code to the GitHub repository. However, this only happens when your build and deploy steps run successfully. While you have sites in production, you can introduce new features without having to pull the site down.

Why use GitHub Actions in your development

  1. Improved and simplified collaboration
    As software development teams scale, quality and reliability of software is not compromised since all workflows are stored in GitHub where everyone can access and contribute. Workflows could also be configured to check every pull request before merging. This ensures code that is below the quality agreed upon from making it to deployment.

  2. Improved workflow visibility
    You can track the progress of your releases and spot any occurring problem because GitHub Actions offers visibility into your build, test and deployment processes. You have a track of how often you have pushed changes to GitHub and deployment history visible.

  3. Automating saves time, increasing speed
    With GitHub Actions, automation of tasks such as building, testing and deployment frees up development teams to focus more on more strategic and creative work. More time is spent in innovation and writing code rather than debugging and writing tests.

  4. Reduced errors
    Automating your build, test, and deploy process reduces the number of errors likely to make it to your software releases. Not only does this improve the quality of your software, but also saves you time and energy.

  5. Security
    You can be confident that your data and code are safe since GitHub Actions shares the same security infrastructure as GitHub. While you could use secrets to protect sensitive data, your GitHub Actions workflows are encrypted while in transit and at rest.


As software development becomes more demanding and complex, and team sizes increase, there is a need to have reliable and quality software. CI/CD are two essential practices in software development. While CI ensures that code changes have been integrated into the codebase automatically and frequently, CD ensures that those changes have been deployed to production reliably and safely. CI/CD can also be used to deploy software to a variety of environments for example, containers such as Kubernetes, edge devices, and in the cloud. GitHub Actions CI/CD is one powerful tool I encourage you to use and you will be shocked by how much you were missing out on. In the future, we can predict more automation on CI/CD and its integration with other devOps tools. GitHub Actions is built on top of GitHub, so there’s no need to learn any new platforms or tools. Creating a new workflow will only take you a few minutes, and there are many pre-made actions available you could use to automate your build, test, and deployment processes.

Top comments (0)