DEV Community

Cover image for Deploy your projects to Github Pages with GitHub Actions
pierresaid
pierresaid

Posted on • Updated on

Deploy your projects to Github Pages with GitHub Actions

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.
Enter fullscreen mode Exit fullscreen mode

The build step

    - name: Install and Build 🔧
      run: |
        npm install
        npm run-script build
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

module.exports = {
    publicPath: process.env.NODE_ENV === 'production'
        ? '/repository-name/'
        : '/'
}
Enter fullscreen mode Exit fullscreen mode
"homepage":"https://yourusername.github.io/repository-name"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Alt Text

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:

Alt Text

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 (14)

Collapse
 
swinton profile image
Steve Winton

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?

Collapse
 
pierresaid profile image
pierresaid • Edited

Thanks!

I just tried it, but it didn't work.
Also, I couldn't find the documentation about this auto generated token.

Collapse
 
swinton profile image
Steve Winton

Hmmm. It’s documented here:

help.github.com/en/articles/virtua...

But maybe it doesn’t carry the right permissions for your use case. Did you get a permissions error?

Thread Thread
 
pierresaid profile image
pierresaid

When the Action try to push the changes, it pops this error in the logs:

fatal: could not read Password for 'https://***@github.com': No such device or address

That must be a permissions error. The personal access token that I generated before (ACCESS_TOKEN) had full control of my private repositories.

Collapse
 
pierresaid profile image
pierresaid

Fixed it ! 👍

Collapse
 
snmi___ profile image
Sanmi

How do we implement the process.env with plain html/css/vanilla js?

Collapse
 
renato66 profile image
Renato Vicente

could you upgrade this article to v3

Collapse
 
pierresaid profile image
pierresaid

Done !

Collapse
 
rsalunga29 profile image
Roland "Akio" Salunga • Edited

Very nice article, thank you for this!

Collapse
 
pierresaid profile image
pierresaid

Thanks 😀

Collapse
 
noamtamim profile image
Noam Tamim

Please explain -- why should I use it? GitHub Pages are already automatically deployed. What am I missing?

Collapse
 
pierresaid profile image
pierresaid • Edited

For project like React, Vue or Angular you will need to build the project to have the html,css and js files that Github Pages can serve.

Github Actions will automate this step for you.

Collapse
 
noamtamim profile image
Noam Tamim

You mean, for sites that are not simple Jekyll? Got it.