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

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
    - name: Install mdbook
      run: |
        mkdir mdbook
        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-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
        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 --set-upstream origin gh-pages

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.

Deploy to Vercel

The following workflow will build the book & deploy the contents to Vercel;

NOTE: The following Environment Variables should be added as "Encrypted Secrets in GitHub";

• VERCEL_TOKEN refers to the special access token which will be used to authenticate the login session in the CI/CD environment. Refer to this support article on Vercel Access Token for more information.
• The VERCEL_PROJECT_ID & VERCEL_ORG_ID are found inside the .vercel/project.json file. The said file is generated by invoking the vercel CLI in your project's local repository.

name: Build Book & Deploy to Vercel

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

on: [push]

jobs:
  buildAndDeploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Install mdBook
        uses: extractions/setup-crate@v1
        with:
          owner: rust-lang
          name: mdBook

      - name: Generate static content for the book
        run: mdbook build

      - name: Setup Node.js (required to install Vercel CLI)
        uses: actions/setup-node@v3

      - name: Install Vercel CLI
        run: npm install --global vercel

      - name: Pull Vercel environment information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy to Vercel
        run: vercel book --prod --token=${{ secrets.VERCEL_TOKEN }}