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 : branches : - master jobs : build-and-deploy : runs-on : ubuntu-latest steps : - name : Checkout 🛎️ uses : actions/checkout@v2 with : persist-credentials : false - name : Install and Build 🔧 run : | npm install npm run-script build - name : Deploy 🚀 uses : JamesIves/github-pages-deploy-action@releases/v3 with : 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.

Options

with : 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

ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}

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.

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"

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:



on : push : branches : - 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.

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 .