How to Publish a Quarto Website with GitHub Actions

Surprisingly simpler than expected.
Quarto
R
GitHub
Author

Kelly Shee

Published

June 7, 2025

Modified

June 26, 2025

You need the following:

Note

This website’s directory is kellyshee.github.io. The directory in the images is quarto_web_tutorial, which I deleted because I dislike underscores in URLs.

1 Create a R project

  1. Navigate to File > New Project > New Directory > Quarto Website.
  2. Directory name
    1. If this website is for . . .
      1. yourself: your-github-username.github.io
      2. class: your-class-name
  3. Create project as subdirectory
    1. Where do you want to place this project? It should be somewhere easy to find, such as on your desktop.
    2. I’ll be creating more version-controlled projects, so I placed this directory (kellyshee.github.io) inside a “github” folder, which is located inside my Box drive. Therefore, this directory’s file path is the following:
├── Box-Box
  ├── github
    ├── kellyshee.github.io
  1. Engine: Knitr
  2. Select Create a git repository
  3. Select Use renv with this project

2 Create a GitHub repo

  1. Go to GitHub.
  2. Click the green “New” button next to “Top repositories” in the left column.
  3. Type your repository name, which must be the same as your directory name.
  4. Do not change anything else. Scroll down to create your repository.

3 Copy Git commands

  1. Scroll to the section that says “. . . or push an existing repository from the command line.”
  2. Copy the first two lines.
  3. Return to RStudio.

4 Paste Git commands into terminal

  1. Navigate to the console pane and switch to the terminal tab.
  2. Paste and enter the commands. The terminal will not return anything.

5 Push local files to repo

  1. Copy and paste the following commands one by one into the terminal. Output will apppear, indicating that files are being uploaded to your repository.
Terminal
git add .
git commit -m "Initial commit"
git push origin main
  1. Return to your GitHub repository and refresh the page. Your project’s files should appear there.

6 Create gh-pages branch

  1. On the same page, click the “main” branch button underneath the repository name.
  2. Click “View all branches.”
  3. Click “New branch” on the right side of the screen.
  4. Name and create a new branch called gh-pages.

7 Create automation file

  1. Return to RStudio and navigate to the file tab in the output pane.
  2. Create a new folder named .github
  3. Inside the .github folder, create another new folder named workflows
  4. Inside the workflows folder, create a text file named publish.yml.

The file path of publish.yml should be the following:

├── ...
  ├── kellyshee.github.io
    ├── kellyshee.github.io.Rproj
    ├── other files
    ├── .github
      ├── workflows
        ├── publish.yml

8 Copy and paste code into publish.yml

Paste the following code into publish.yml, then save the file.

.github/workflows/publish.yml
# Knitr with renv

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

9 Push publish.yml to repo

  1. Return to the terminal tab in the console pane.
  2. Copy and paste the following commands line by line into the terminal. Output will appear.
Terminal
git add .
git commit -m "Add publish.yml to automate publishing of site"
git push origin main

10 Check repo settings

  1. Return to GitHub.
  2. Click on the Actions tab. Wait until all actions are green.
  3. Click on the “Settings” tab. Look at the side column and click “Pages.” Ensure that your GitHub Pages site is built from the gh-pages branch.
  4. Click “Visit site” at the top of the page. Whenever you edit this site in RStudio, you can use the three Git commands to publish it automatically. It’ll take a couple minutes for the site to change.

11 Credit

I learned this from a video by Melissa Van Bussel. My tutorial differs from hers in that I use RStudio’s terminal instead of a Windows terminal with zsh.

I frequently forget the things I’ve learned, and it’s annoying having to dig through paper notebooks. Obsidian, Notion, and other software are additionally annoying because I keep overfixating on settings.

You know what isn’t so terrible? RStudio (it helps that I’ve been acquainted with it since 2018). It’s nice having your own website to reference while also doubling as your portfolio. So, if you’re like me, create your own website!