Automated Deployment: GitHub Actions

The following examples show various ways to use GitHub Actions. Some of these examples will publish to GitHub Pages

Real-world examples

The examples below are simplified, intended to illustrate basic usage. Real-world projects tend to be more complicated or have more requirements. The following links are to some real-world projects, which you may want to look at for more complex examples:

• rgarrigue/songbook
• MichaelCurrin/mdbook-quickstart
• gbdev/pandocs
• rust-lang/mdbook
• rust-lang/cargo
• rust-lang/book

Running Rust tests

If you want to run mdbook test to test Rust examples, the following GitHub Action will run the tests on every PR and push.

name: CI
on: [push, pull_request]

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - name: Install Rust
      run: |
        rustup set profile minimal
        rustup toolchain install stable
        rustup default stable
    - name: Install mdbook
      run: |
        mkdir bin
        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
        echo "$(pwd)/bin" >> $GITHUB_PATH
    - name: Run tests
      run: mdbook test

GitHub Pages Deploy

The following example shows a basic example that does not require any external actions or dependencies to deploy to GitHub Pages. Add this file to .github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
    - name: Install mdbook
      run: |
        mkdir mdbook
        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
        echo `pwd`/mdbook >> $GITHUB_PATH
    - name: Deploy GitHub Pages
      run: |
        # This assumes your book is in the root of your repository.
        # Just add a `cd` here if you need to change to another directory.
        mdbook build
        git worktree add gh-pages gh-pages
        git config user.name "Deploy from CI"
        git config user.email ""
        cd gh-pages
        # Delete the ref to avoid keeping history.
        git update-ref -d refs/heads/gh-pages
        rm -rf *
        mv ../book/* .
        git add .
        git commit -m "Deploy $GITHUB_SHA to gh-pages"
        git push --force

XAMPPRocky/deploy-mdbook

The following example uses an action from https://github.com/XAMPPRocky/deploy-mdbook to publish to GitHub Pages.

name: Deploy mdBook
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: XAMPPRocky/[email protected]
        with:
            token: ${{ secrets.GITHUB_TOKEN }}

JamesIves/github-pages-deploy-action

The following example uses an action from https://github.com/JamesIves/github-pages-deploy-action to publish to GitHub Pages.

The following .github/workflows/main.yml will ensure that mdbook build and mdbook test run successfully, and deploy to GitHub Pages.

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    name: Build, Test and Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - run: (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.4" mdbook)
      - run: mdbook build && mdbook test # In case of custom book path: mdbook build path/to/mybook && mdbook test path/to/mybook
      - uses: JamesIves/[email protected]
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: book # The folder the action should deploy.