publish

Publishing with Quarto using GitHub Actions

Important: unlike upstream’s quarto-actions/publish, the to argument is not available and the target argument must be used.

This README complements the more detailed documentation on Quarto's website.

Netlify

See also https://quarto.org/docs/publishing/netlify.html about Netlify publishing support in Quarto.

1. Create Netlify auth token. Go to Netlify's applications page, and click on "New Access Token" to create a new personal access token. Give this token a memorable name, and note the resulting string (or keep this window open in a tab)

2. Add Netlify auth token to your repository's secrets. Go to the repository that will be using this GHA. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use NETLIFY_AUTH_TOKEN, and for the "Value" field, paste the string you got from step 1.

3. Add the GitHub Actions workflow to your project. (Use quarto-publish-example.yml as an example).

4. Add _publish.yml to your repository. Quarto stores publishing metadata information in _publish.yml. To create this file, run quarto publish netlify locally once.

5. Configure action to use netlify:

   - name: Publish to Netlify (and render)
     uses: quarto-dev/quarto-actions/publish@v2
     with:
       target: netlify
       NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

GitHub Pages

See also https://quarto.org/docs/publishing/github-pages.html about Github Pages publishing support in Quarto.
And https://quarto.org/docs/publishing/github-pages.html#github-action about using Github Actions to publish to Github Pages with Quarto.

1. Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run quarto publish gh-pages locally, once. This will create a new branch called gh-pages and push it to the remote repository, and configure the gh-pages branch to be the publishing source for GitHub Pages.

2. Then you need to configure your repo to use Github Actions to publish, by adding GitHub Actions workflow to your project.

   • Use quarto-publish-example.yml as an example
   • Go over our documentation for additional details at https://quarto.org/docs/publishing/github-pages.html#github-action

Details on how to configure the GitHub Actions workflow

When using quarto-dev/quarto-actions/publish, configure it to use gh-pages as publishing target:

- name: Publish to GitHub Pages (and render)
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions

If you not using quarto-publish-example.yml, check the minimum required access for the publish action: You need to set contents permissions to write.

permissions:
  contents: write

See Github's documentation on permissions for more details

• Setting permissions for a workflow: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#permissions
• Setting permissions for a workflow job: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions
• About GITHUB_TOKEN permissions: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token

Posit Connect

See also https://quarto.org/docs/publishing/rstudio-connect.html about Posit Connect publishing support in Quarto.

1. Create Posit Connect auth token. After logging in to your Posit Connect server, click on your username on the top right. A sidebar should slide in from the right. Click on "API keys". On the new page, click on the "New API Key" button. Give it a memorable name and note the resulting string (or keep this browser window open).

2. Add Posit Connect auth token to your GitHub repository. Go to the GitHub webpage for the repository that will be using this GitHub Action. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use CONNECT_API_KEY, and for the "Value" field, paste the string you got from step 1.

3. Add the GitHub Actions workflow to your project. (Use quarto-publish-example.yml as an example).

4. Add _publish.yml to your repository. Quarto stores publishing metadata information in _publish.yml. To create this file, run quarto publish connect locally once.

5. Configure action to use Posit Connect:

   - name: Publish to Posit Connect (and render)
     uses: quarto-dev/quarto-actions/publish@v2
     with:
       target: connect
       CONNECT_SERVER: enter-your-server-url-here
       CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }} 

Other configurations available for Quarto Publish action

The with parameter can also be set to configure the following

• path: Subdirectory containing the quarto project to be published or path to individual .qmd file. Default to working directory (.)
• render: Set to render: "false" to skip rendering of project before publishing. By default, this publish action will render to all formats defined.

Rendering with a Quarto profile

quarto publish will render first by default. You can render with a specific profile by setting the QUARTO_PROFILE environment variable. For example, to publish the version correspondig with the preview profile of your website (i.e. you have a _quarto-preview.yml file in your project), you can do:

- name: Render Quarto Project
  uses: quarto-dev/quarto-actions/render@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions
    QUARTO_PROFILE: preview
  with:
    target: gh-pages