Deploy to Github Pages

Status: production

This workflow is stable and widely used in production environments.

Build and deploy an application to GitHub pages.

Purpose

This workflow will build and deploy a static application to GitHub pages.

Usage

Minimal Example

Below is an example of the minimal configuration required to run the workflow. It's based on sensible defaults but will not satisfy all use cases.

To see how to customise the job(s) to work for your case, refer to inputs, secrets and the Additional examples.

Bare minimum code to insert in your workflow

jobs:
  deploy-pages:
    uses: erzz/toolbox/.github/workflows/deploy-pages.yml@v1
    # no mandatory inputs
    # no mandatory secrets

Inputs

Input	Type	Description	Required	Default
install-command	string	The command to install dependencies required to build site	false	yarn install
build-command	string	The command to build the site	false	yarn build
publish-dir	string	The directory, containing the built site, to publish	false	./build
force-orphan	boolean	Prevent your repo from bloating by using only the latest commit for gh-pages branch	false	true
cname	string	If fronting with a custom domain, specify the cname	false	null
setup-node	boolean	To install a custom version of NodeJS, set to true	false	true
node-version	string	The version of NodeJS to install	false	20
pre-commands	string	Commands to run before building the site. Use | for multiple commands	false	null
artifact	boolean	If true, the built site will be uploaded as an artifact (can be slow!)	false	false

Secrets

Input	Description	Required
auth-token	Arbitrary token to be exposed as environment variable in the format VARIABLE=value	false
auth-token-2	Arbitrary token to be exposed as environment variable in the format VARIABLE=value	false

Outputs

No outputs provided by this workflow

Configuration Notes

Enable Pages

Currently, pages needs to be enabled manually in the repository settings. This is a one-time task which in the near future will also be more easily automated but the functionality is still in Alpha at Github.

So for now, you must configure the repository Settings > Pages. Typically you would configure:

• Source: Deploy from a branch
• Branch: gh-pages
• Directory: / (root)
• Custom domain: (if you have one)

Build authentication

Secrets are provided for build-time authentication with private package registries such as Artifactory, NPM etc.

There are options to provide an auth-token and/or auth-token-2 where the environment variable they are exposed as is configurable.

For example you could expose auth-token: NPM_TOKEN=${{ secrets.SOME_SECRET }} or auth-token: ARTIFACTORY_AUTH_TOKEN=${{ secrets.SOME_SECRET }} depending on what your build process requires.

Pre commands

There are options to run pre-commands before the install and build of your site if required.

Force orphan

By default, the gh-pages branch is created as an orphan branch with only the latest build. This is to stop your repository ballooning in size with every build due to a commit history full of compiled files. If you need to keep the history of the gh-pages branch you can disable this feature.

Disable NodeJS

This workflow assumes you will need NodeJS by default. Not every site does (Hugo for example) so the workflow can be configured to disable the setup of NodeJS and shave a few seconds off the build time.

Additional Examples

Run pre-commands

Useful for installing extra binaries, dependencies or manipulating files before the build.

deploy-pages:
  uses: ingka-group-digital/workflows/.github/workflows/deploy-pages.yml@v2
  with:
    pre-commands: |
      echo "Installing dart-sass"
      sudo snap install dart-sass

Custom commands & Auth tokens

Most relevant commands are customisable, even with multiple commands using the | syntax. You can pass in any environment variables you need to the commands for authentication with private package registries.

deploy-pages:
  uses: ingka-group-digital/workflows/.github/workflows/deploy-pages.yml@v2
  with:
    install-command: npm ci
  secrets:
    auth-token: "NPM_TOKEN=${{ secrets.GH_NPM_AUTH_TOKEN }}"
    auth-token-2: "ARTIFACTORY_AUTH_TOKEN=${{ secrets.ARTIFACTORY_AUTH_TOKEN }}"

Workflow details

Source code

View on Github

.github/workflows/deploy-pages.yml

name: Deploy to GitHub Pages
permissions:
  pages: write
  id-token: write
  contents: write
on:
  workflow_call:
    inputs:
      install-command:
        type: string
        description: The command to install dependencies required to build site
        required: false
        default: yarn install
      build-command:
        type: string
        description: The command to build the site
        required: false
        default: yarn build
      publish-dir:
        type: string
        description: The directory, containing the built site, to publish
        required: false
        default: ./build
      force-orphan:
        type: boolean
        description: Prevent your repo from bloating by using only the latest commit for
          gh-pages branch
        required: false
        default: true
      cname:
        type: string
        description: If fronting with a custom domain, specify the cname
        required: false
      setup-node:
        type: boolean
        description: To install a custom version of NodeJS, set to true
        required: false
        default: true
      node-version:
        type: string
        description: The version of NodeJS to install
        required: false
        default: "20"
      pre-commands:
        type: string
        description: Commands to run before building the site. Use | for multiple commands
        required: false
      artifact:
        type: boolean
        description: If true, the built site will be uploaded as an artifact (can be slow!)
        required: false
        default: false
    secrets:
      auth-token:
        required: false
        description: Arbitrary token to be exposed as environment variable in the format
          VARIABLE=value
      auth-token-2:
        required: false
        description: Arbitrary token to be exposed as environment variable in the format
          VARIABLE=value
jobs:
  deploy:
    name: Deploy to pages
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup NodeJS
        if: ${{ inputs.setup-node == 'true' }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - name: Export auth token 1
        env:
          TOKEN: ${{ secrets.auth-token }}
        if: ${{ env.TOKEN != '' }}
        run: |
          echo "::add-mask::${TOKEN#*=}"
          echo "${{ env.TOKEN }}" >> $GITHUB_ENV
      - name: Export auth token 2
        env:
          TOKEN: ${{ secrets.auth-token-2 }}
        if: ${{ env.TOKEN != '' }}
        run: |
          echo "::add-mask::${TOKEN#*=}"
          echo "${{ env.TOKEN }}" >> $GITHUB_ENV
      - name: Run pre-commands
        run: |
          ${{ inputs.pre-commands }}
      - name: Build Site
        run: |
          ${{ inputs.install-command }}
          ${{ inputs.build-command }}
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ github.token }}
          publish_dir: ${{ inputs.publish-dir }}
          cname: ${{ inputs.cname }}
          force_orphan: ${{ inputs.force-orphan }}
      - name: Upload site as artifact
        uses: actions/upload-artifact@v4
        if: ${{ inputs.artifact == 'true' }}
        with:
          name: Site
          path: ${{ inputs.publish-dir }}

Job definitions

Step	Uses	Conditional
Checkout	actions/checkout@v4	false
Setup NodeJS	actions/setup-node@v4	true
Export auth token 1	script	true
Export auth token 2	script	true
Run pre-commands	script	false
Build Site	script	false
Deploy	peaceiris/actions-gh-pages@v4	false
Upload site as artifact	actions/upload-artifact@v4	true

Configuration Files

This workflow does not provide any default configuration files