/zola-deploy-action

Github action for building a Zola site and deploying to Github Pages

Primary LanguageHTMLMIT LicenseMIT

Zola Deploy Action

Build Status GitHub release (latest SemVer)

A GitHub action to automatically build and deploy your zola site to the master branch as GitHub Pages.

Table of Contents

Usage

This example will build on push to any branch, then deploy to gh-pages.

on: push
name: Build and deploy on push
jobs:
  build:
    name: shalzz/zola-deploy-action
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: shalzz/zola-deploy-action
      uses: shalzz/zola-deploy-action@master
      env:
        PAGES_BRANCH: gh-pages
        BUILD_DIR: docs
        BUILD_FLAGS: --drafts
        TOKEN: ${{ secrets.TOKEN }}

This example will build and deploy on master branch to gh-pages branch. Additionally will build only on pull requests.

on:
  push:
    branches:
      - master 
  pull_request:
jobs:
  build:
    runs-on: ubuntu-latest
    if: github.ref != 'refs/heads/master'
    steps:
      - name: 'Checkout'
        uses: actions/checkout@master
      - name: 'Build only' 
        uses: shalzz/zola-deploy-action@master
        env:
          BUILD_DIR: .
          TOKEN: ${{ secrets.TOKEN }}
          BUILD_ONLY: true
  build_and_deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/master'
    steps:
      - name: 'Checkout'
        uses: actions/checkout@master
      - name: 'Build and deploy'
        uses: shalzz/zola-deploy-action@master
        env:
          PAGES_BRANCH: gh-pages
          BUILD_DIR: .
          TOKEN: ${{ secrets.TOKEN }}

Secrets

  • TOKEN: Personal Access key with the appropriate scope. If the repository is public the public_repo scope suffices, for private repositories the full repo scope is required. We need this to push the site files back to the repo.

    ( Actions already provides a GITHUB_TOKEN which is an installation token and does not trigger a GitHub Pages builds hence we need a personal access token )

Environment Variables

  • PAGES_BRANCH: The git branch of your repo to which the built static files will be pushed. Default is gh-pages branch
  • REPOSITORY: The target repository to push to. Default is GITHUB_REPOSITORY(current repository). Set this variable if you want to deploy to other repo.
  • BUILD_DIR: The path from the root of the repo where we should run the zola build command. Default is . (current directory)
  • BUILD_FLAGS: Custom build flags that you want to pass to zola while building. (Be careful supplying a different build output directory might break the action).
  • BUILD_ONLY: Set to value true if you don't want to deploy after zola build.
  • BUILD_THEMES: Set to false to disable fetching themes submodules. Default true.

Custom Domain

If you're using a custom domain for your GitHub Pages site put the CNAME in static/CNAME so that zola puts it in the root of the public folder which is where GitHub expects it to be.