When publish with GitHub Actions, which branch should I push to: gh-pages or main?

[nataschake]

Description

Hi! I read the doc on how to publish Quarto presentations with GitHub Actions and see that in /.github/workflows/publish.yml file target push is expected to main branch:

on:
  workflow_dispatch:
  push:
    branches: main

whereas below I see that render and publish uses target branch gh-pages:

  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
...
      - name: Render and Publish
        with:
          target: gh-pages

Later on it is written that whenever I push to main branch, GitHub Action is performed.
I understand that quarto publish gh-pages updates the resulting presentation .html files, but they are updated in gh-pages branch, not in main branch. So main branch has no files at all, at least if one follows the instruction mentioned above.
What action do I miss?
Thanks!

[cderv]

This is working as expected. quarto publish gh-pages is a helper to publish to Github Pages. Github pages can have different publising source, and a branch is one of them. gh-pages is the convention widely use to name this branch.
This is explained in Github Pages doc at : https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

Quarto docs explains you which configuration you need to do to set up your repository: https://quarto.org/docs/publishing/github-pages.html#source-branch

In this workflow

• Your source code lives in main
• Your published website lives in gh-pages

Github Pages offers other way to publish. You could configuration your repo to publish to Github Pages from another branch, or a folder within that branch. Look at the doc.

There is also a way to publish to Github pages using Github Actions directly. This is explain in the next chapter. https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
In that case, this would means

• You render your website from the source using Github Actions
• After the website is rendered directly within the workflow action you publish the built website using the actions/upload-pages-artifact. This is what is described in the link above.

In Quarto doc we recommend a workflow. If you want to use another, you can definitely to it. This has nothing to do with how quarto works. In all case you will render the source file to an output (here a website), and then you can publish this output the way you want.

Hope it helps understand

[nataschake]

Ok, will look at.