Experience about deploying mdbook on github using github action

[vague]

Just want to share the experience I get lately. And I'm a noob about CI/CD...

Used to be this

peaceiris/actions-gh-pages is simple to use, which is a traditional way via creating a new branch called gh-pages every time before deployment. This causes the repo size bloats.

# Just my workflow
name: github pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'

      - name: Setup mdbook-theme latest
        run: |
          curl -s https://api.github.com/repos/zjp-CN/mdbook-theme/releases/latest \
               | grep browser_download_url \
               | grep mdbook-theme_linux \
               | cut -d '"' -f 4 \
               | wget -qi -
          tar -xvzf mdbook-theme_linux.tar.gz
          echo $PWD >> $GITHUB_PATH
      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book
          force_orphan: true
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'
          commit_message: ${{ github.event.head_commit.message  }}

Now can be this

After switching to Github Actions in the Pages Setting, you'll get a basic yml file (pages.yml) to edit. This means the generated static files will be uploaded and never take up the space of your repo.

# build.yml
name: Mdbook build

on:
  push:
    branches: ["main"]

jobs:
  build:
    name: build
    runs-on: ubuntu-latest
    env:
      MDBOOK_VERSION: '0.4.12'
      MDBOOK_LINKCHECK_VERSION: '0.7.4'
      MDBOOK_MERMAID_VERSION: '0.8.3'
    steps:
    - uses: actions/checkout@v2
      with:
        submodules: true
    - name: Install mdbook
      run: |
        mkdir ~/tools
        curl -L https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C ~/tools
        curl -L https://github.com/badboy/mdbook-mermaid/releases/download/v$MDBOOK_MERMAID_VERSION/mdbook-mermaid-v$MDBOOK_MERMAID_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C ~/tools
        curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v$MDBOOK_LINKCHECK_VERSION/mdbook-linkcheck.v$MDBOOK_LINKCHECK_VERSION.x86_64-unknown-linux-gnu.zip -O
        unzip mdbook-linkcheck.v$MDBOOK_LINKCHECK_VERSION.x86_64-unknown-linux-gnu.zip -d ~/tools
        chmod +x ~/tools/mdbook-linkcheck
        curl -s https://api.github.com/repos/zjp-CN/mdbook-theme/releases/latest \
               | grep browser_download_url \
               | grep mdbook-theme_linux \
               | cut -d '"' -f 4 \
               | wget -qi -
        tar -xzf mdbook-theme_linux.tar.gz -C ~/tools
        echo ~/tools >> $GITHUB_PATH
    - name: Build
      run: mdbook build
    # share between different jobs
    - uses: actions/upload-artifact@v3
      with:
        name: book
        path: book/

# pages.yml
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
  workflow_run:
    workflows: ["Mdbook build"]
    types:
      - completed

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Disallow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      # actions/download-artifact@v3 does not allow sharing across workflows
      - name: Download artifact
        id: download-artifact
        uses: dawidd6/action-download-artifact@v2
        with:
          name: book
          path: book/
          workflow: build.yml
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: book
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Here I split the workflow into two files:

• build.yml
  • Install mdbook and its plugins to ~/tools with GITHUB_PATH set up
  • mdbook build: this will create book/ dir
    • normally you just need to deploy book/
    • mdbook plugins will create its own directories under book/, so book/html/ is the deployment dir
  • Upload artifacts
    • pack up book/ and give it a name book
    • this is one of the two ways to share things between jobs or workflows (another is to cache)
• pages.yml
  • Most content is given by github action, and you need to set
    • cancel-in-progress: false: otherwise you might get Canceling since a higher priority waiting request for 'pages' exists error and receive spams for failing CI.
    • The path in actions/upload-pages-artifact as the deployment dir
  • Add workflow_run to specify this workflow must await the build.yml to finish (but you have to use the workflow name instead of file name)
  • Download the artifacts via dawidd6/action-download-artifact
    • Just specify the name and path when uploading

Hmm... The template repo is here.
Hope this will save your time when you switch to the github action way.