Deploy your projects to Github Pages with GitHub Actions
Tags: github, webdev, devops
Published: 2019-08-31 21:02:06

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](https://github.com/marketplace/actions/deploy-to-github-pages).


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

```yml

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
```yml
    - 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
```yml
      with:
        branch: gh-pages
        folder: dist
```

All those options are environment variables that will be used by the [Deploy to GitHub Pages Action](https://github.com/marketplace/actions/deploy-to-github-pages) 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](https://github.com/settings/tokens) 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](https://cli.vuejs.org/config/#publicpath).

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

* For React.js apps add this your `package.json`. [Further information](https://create-react-app.dev/docs/deployment#building-for-relative-paths).

```json
"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.

``` yml
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.

![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/1djjhixx18vkdh8n9sl5.png)

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](https://thepracticaldev.s3.amazonaws.com/i/ys92cfjv10gdk7onx63f.png)

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`