Deploy your projects to Github Pages with GitHub Actions

#github #webdev #devops

In this post I am going to explain how to set up a basic workflow that uses an existing GitHub action. This workflow will deploy a static web site to GitHub Pages every time a change is made to the master branch.

For this we are going to use the Deploy to GitHub Pages Action.

Create our workflow

The workflows of the repository are stored in the .github/workflows/ folder.

Create in this folder a .yml file (e.g. deploy-to-gh-pages.yml you can name it however you want) and paste this:


name: Build and Deploy
on: [push] # defaults to master
permissions:
  contents: write
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3

      - name: Install and Build 🔧
        run: |
          npm install
          npm run-script build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build # The folder the action should deploy.

The build step

    - name: Install and Build 🔧
      run: |
        npm install
        npm run-script build

In this section we put the script required to compile the code before deploying. If there is no need just remove this section.

Options

      with:
        branch: gh-pages
        folder: dist

All those options are environment variables that will be used by the Deploy to GitHub Pages Action in order to work.

The BRANCH option is the branch you wish to deploy the build files to. It is gh-pages by default so that github automatically set up your github pages website.

You need to create the gh-pages branch prior to this. The Action will fail if the branch does not exist.

The folder option is the folder in your repository that you want to deploy. It usually is dist for Vue.js apps or build for React.js apps.

the permissions filed is required so that the script has sufficient rights to run.

Optionally if you want to use a specific access token you can add the token option like this:

token: ${{ secrets.ACCESS_TOKEN }}

This option is the access token used to authorize the action to manipulate your repository.

You can generate this token in Profile Settings / Developer settings and add it in your repository's secrets in Settings/Secrets

Custom domain name

If you are using a custom domain name you will need to add beforehand a CNAME file at the root of the gh_pages branch with your domain name in it.

e.g. dev.to

If you are not using a custom domain name, then do not forget to specify that your project is not hosted at the server root.

For Vue.js apps add this in vue.config.js. Further information.

module.exports = {
    publicPath: process.env.NODE_ENV === 'production'
        ? '/repository-name/'
        : '/'
}

For React.js apps add this your package.json. Further information.

"homepage":"https://yourusername.github.io/repository-name"

Specify the branch (Optional)

By default, this will use the master branch when changes are made.

To change that replace the on: [push] for this property with name of the branch of which you'd like this to run on.

on:
  push:
    branches:
      - main

note: Your workflows won't appear in the Actions tab if they are not pushed on the master branch. However, you can still access your workflow’s runs in the commit's detail.

That's it! Push your changes and you can now watch the magic operate in the Actions tab.

And we can see that the app was deployed to GitHub Pages You can check out your deployments by clicking the environment button in the Code tab:

You might have to disable/enable the github page option in the settings tab the first time the action run. You can do that by changing the Source setting to master then back to gh-pages.

The link to your live app is https://yourusername.github.io/repository-name

Top comments (12)

Steve Winton • Sep 1 '19

Nice write up!

I think ${{ secrets.ACCESS_TOKEN }} in your example can be replaced with ${{ secrets.GITHUB_TOKEN }}, which is a repo-scoped token automatically generated for you by GitHub. Did you try this?