quarto-publish.yml

Render a Quarto project and deploy it to the gh-pages branch, which GitHub Pages serves. One-time setup: set Settings -> Pages -> Source to “Deploy from a branch”, branch gh-pages / (root). Render-only callers (deploy: false) skip the deploy.

Inputs

Input	Type	Default	Description
path	string	'.'	Path in the caller repo to the Quarto project to render (the directory with _quarto.yml).
setup-r	boolean	false	Install R and project R dependencies before rendering (for R/knitr Quarto projects).
r-packages	string	(long; see workflow file)	r-lib/actions package specs installed when setup-r is true and use-renv is false. Defaults to any::knitr and any::rmarkdown.
use-renv	boolean	false	Restore R dependencies with renv instead of r-packages (requires setup-r).
tinytex	boolean	false	Install TinyTeX (needed to render PDF outputs).
apt-packages	string	''	Extra apt packages to install before rendering (space-separated).
output-dir	string	'_site'	Directory the rendered site is written to, relative to path; forwarded to quarto render --output-dir and overrides any _quarto.yml setting.
checkout-submodules	boolean	false	Initialize the caller’s git submodules before rendering.
pre-render-artifact	string	''	Name of a workflow-run artifact to download into the project before rendering, so an earlier job can inject build-time assets. Empty to skip.
pre-render-artifact-path	string	''	Directory in the caller repo to extract pre-render-artifact into. Defaults to the workspace root.
deploy	boolean	true	Deploy the rendered site to the gh-pages branch. Set false to render only.

Secrets

Secret	Required	Description
SUBMODULES_TOKEN	no	Token with read access to private submodules (only needed when checkout-submodules is true).

Permissions

Grant contents: write (the deploy job pushes to gh-pages). Grant it even with deploy: false: a reusable workflow’s caller must grant a job’s permissions even when that job is skipped, and the deploy job is part of the workflow. The build job downscopes its own token to contents: read.

Example

# Copy to .github/workflows/quarto-publish.yml in your repo.
#
# Renders a Quarto site and deploys it to the gh-pages branch (which GitHub
# Pages serves). The calling job must grant contents: write so the deploy step
# can push to gh-pages (repos default to a read-only token).
#
# One-time repo setup: Settings -> Pages -> Build and deployment -> Source =
# "Deploy from a branch", branch `gh-pages` / `(root)`.
name: Quarto Publish

on:
  push:
    branches: [main]
  workflow_dispatch:
  # For a render-only build check (deploy: false below), also add:
  # pull_request:

# Serialize deploys so two pushes don't race on the gh-pages branch.
concurrency:
  group: gh-pages
  cancel-in-progress: false

jobs:
  publish:
    permissions:
      # Push the rendered site to gh-pages. Grant this even with deploy: false
      # (render only): the workflow's deploy job declares contents: write, and a
      # reusable workflow's caller must grant a job's permissions even when that
      # job is skipped. The build job downscopes its own token to read.
      contents: write
    uses: Morrison-Lab/gha/.github/workflows/quarto-publish.yml@v2
    # with:
    #   path: website          # Quarto project lives in a subdir (default: repo root)
    #   setup-r: true           # for R/knitr Quarto projects (default: false)
    #   use-renv: true          # restore R deps with renv instead of r-packages
    #   tinytex: true           # needed to render PDF outputs
    #   output-dir: docs        # render to a dir other than the default _site (overrides _quarto.yml)
    #   checkout-submodules: true
    #   pre-render-artifact: demo-media       # inject a prior job's artifact before render
    #   pre-render-artifact-path: website/media
    #   deploy: false           # render only (e.g. a build check); skips the gh-pages push
    #                           # (still grant contents: write; the deploy job is declared)
    # secrets:
    #   SUBMODULES_TOKEN: ${{ secrets.SUBMODULES_TOKEN }}

See examples/quarto-publish.yml for the full caller stub.