2  Building on Github Actions with Nix

2.1 Setup

Just like when building using the usual approches, you first need to build the book locally, on your computer, once. For this, after having generated the default.nix file, you can build the environment using nix-build, and then drop in a shell with nix-shell (if this previous sentence is confusing, make sure you read the vignette linked at the end of the previous chapter).

Once in that shell, run quarto publish gh-pages. This will render the book, and make sure that everything gets setup properly. If the book does not render, this could mean that you’re missing some dependency. Make sure to specify all the requirements in the define_env.R script and that you re-generated the default.nix file. If the quarto publish gh-pages command succeeds, you’re all set. Editing the book and pushing will build the book on Github Actions.

2.2 The Github Actions workflow file

Here is what the workflow file looks like:

name: Build book using Nix

on:
  push:
    branches:
      - main
      - master

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Code
      uses: actions/checkout@v3

    - name: Install Nix
      uses: DeterminateSystems/nix-installer-action@main
      with:
        logger: pretty
        log-directives: nix_installer=trace
        backtrace: full

    - name: Nix cache
      uses: DeterminateSystems/magic-nix-cache-action@main

    - name: Build development environment
      run: |
        nix-build

    - name: Publish to GitHub Pages (and render)
      uses: b-rodrigues/quarto-nix-actions/publish@main
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

The first step Checkout code makes the code available to the rest of the steps. I then install Nix on this runner using the Determinate Systems nix-installer-action and then I use another action from Determinate Systems, the magic-nix-cache-action. This action caches all the packages so that they don’t need to get re-built each time a change gets pushed, speeding up the process by a lot. The development environment gets then built using nix-build.

Finally, an action I defined runs, quarto-nix-actions/publish. This is a fork of the quarto-actions/publish action which you can find here. My fork simply makes sure that the quarto render and quarto publish commands run in the Nix environment defined for the project.