How to Automate Quarto Builds with GitHub Actions

How-to
CI:CD
Front End Dev
Setting up a website with Quarto? Want to automate the website build and publication with GitHub Actions? Could you use a quick guide? I’ve got your back.
Author

Rich Leyshon

Published

September 10, 2023

Assumptions

  • You’re set up with a GitHub account.
  • You’re able to run git commands [1] from a command line interface (CLI).
  • You’ve installed quarto. [2]
  • You’ve a preferred text editor installed, eg Visual Studio Code, Atom or similar.

This guide is based on the useful quarto continuous integration (CI) documentation [3] and the examples provided within the Quarto CI GitHub repository [4].

CI for Quarto

The repository used for setting up this example is available on GitHub.

The renderred site should look like this on GitHub Pages.

In the GitHub User Interface

  1. Create a repository.
  2. Copy the clone url.

In the CLI

  1. cd to wherever you would like to keep your local clone.
  2. git clone <INSERT REPO URL>
  3. cd <INSERT REPO PATH>
  4. touch .github/workflows/publish-quarto.yml
  5. touch index.qmd
  6. touch .nojekyll
  7. touch _quarto.yml

In the text editor

  1. Copy and paste the below into .github/workflows/publish-quarto.yml (you may need to enable viewing hidden files on your system - command + shift + . On macOS):
name: Render and Publish
on:
  push:
    branches:
      - main  # changes pushed to this branch will trigger a build.

jobs:
  build-deploy:
      runs-on: ubuntu-latest
      permissions:
        contents: write
      steps:
        - name: Check out repository
          uses: actions/checkout@v3
          
        - name: Set up Quarto
          uses: quarto-dev/quarto-actions/setup@v2
          with:
            version: 1.3.340

        - name: Publish to GitHub Pages (and render)
          uses: quarto-dev/quarto-actions/publish@v2
          with:
            target: gh-pages # renderred html files will be pushed here
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions
  1. Copy paste the below into the index.qmd, using your preferred text editor:
---
title: Hello Quarto CI
date: last-modified
resources:
  - .nojekyll
---
Setting up CI for quarto website build & publish.
  1. Copy paste the following into _quarto.yml:
project:
  type: website
  output-dir: docs
execute:
  freeze: auto
format: html

Back in the CLI

  1. At the project root: quarto render. This will make a docs folder with your rendered website, a directory called index_files with more site dependencies and a .gitignore file. The only file needed to be committed is the .gitignore.
  2. echo /docs/ >> .gitignore
  3. echo /index_files/ >> .gitignore
  4. git status should look like this:
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .github/workflows/publish-quarto.yml
        .gitignore
        _quarto.yml
        index.qmd
  1. git add .
  2. git commit -m "Configure quarto"
  3. git push

Back to the Web Browser

  1. If the push was successful, navigate to your repository
  2. Click on the drop down arrow next to main branch
  3. Click on ‘view all branches’
  4. Click the ‘new branch’ button
  5. Create the branch gh-pages
  6. Click on ‘settings’ in the top ribbon of the repo site
  7. Click on ‘Pages’ in the menu to the left
  8. Check that your GitHub Pages is setup is Build and deployment > Source > Deploy from a branch
  9. Check that the Branch setup is gh-pages /root
  10. After the CI has finished building, you can click on the url that appears at the top of this page under “GitHub Pages” to check that the site has been deployed properly. Copy the url of your GitHub Pages site.

Head Back to your Local Repo

  1. Insert your url into your _quarto.yml, like below:
project:
  type: website
  output-dir: docs
execute:
  freeze: auto
format: html
website:
  site-url: "<YOUR_URL_HERE>" # makes site links work on your remote site

Creating a Workflow Build Status Badge

  • Use the following format to create a workflow build status badge in your readme: https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg
    For example: https://github.com/r-leyshon/quarto-ci-example/actions/workflows/publish-quarto.yml/badge.svg
  • Finally, embed the url in the src of a markdown image, like: ![example workflow](https://github.com/r-leyshon/quarto-ci-example/actions/workflows/publish-quarto.yml/badge.svg)

example workflow

fin!

References

[1]
GitHub, “Getting Started with Git.” https://docs.github.com/en/get-started/getting-started-with-git
[2]
Quarto, “Hello Quarto.” https://quarto.org/docs/get-started/hello/rstudio.html
[3]
Quarto, “Publishing with Continuous Integration.” https://quarto.org/docs/publishing/ci.html
[4]
Quarto, “Quarto Developers CI Repository.” https://github.com/quarto-dev/quarto-actions