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

Deploy your projects to Github Pages with GitHub Actions

pierresaid profile image pierresaid Updated on ・3 min read

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
      - master
    runs-on: ubuntu-latest
      - name: Checkout 🛎️
        uses: actions/checkout@v2.3.1
          persist-credentials: false 

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

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@3.6.2
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: dist

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.


        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        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 GITHUB_TOKEN option is the access token used to authorize the action to manipulate your repository. Here we use GITHUB_TOKEN wich is a repo-scoped token automatically generated for you by GitHub.

You could also generate an access token in Profile Settings / Developer settings and add it in your project's secrets in Settings/Secrets and then change
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} to

The BRANCH option is the branch you wish to deploy the build files to. In this case gh-pages. Keep it that way 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.

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/'
        : '/'

Change the default branch (Optional)

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

To change that add the BASE_BRANCH option in with with the name of the branch of which you'd like to checkout prior to deploying.

e.g. BASE_BRANCH: prod

You will also need to change this part in your workflow file:

      - master

This part specifies which branch to watch for changes. In this case the Action will be triggered when any changes occur on the master branch.

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

Posted on by:


Editor guide

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?



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


Hmmm. It’s documented here:


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

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.


Please correct the misleading article title. GitHub pages will only host static html - not run Node.js.


Fixed it ! 👍


could you upgrade this article to v3


Very nice article, thank you for this!


Thanks 😀


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


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.


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