GHA to Github Pages: misleading error + need for documentation

[petrbouchal]

When using the publish action on GHA as per documentation, I ended up with the following error:

ERROR: No _publish.yml file available (_publish.yml specifying a destination required for non-interactive publish).

As it turns out, the actual problem was that quarto publish gh-pages had not been run locally, as the documentation for the action suggests one does before running the action. After doing this, the action ran as expected, without the need for any other tweaks and also without needing to include a _publish.yml file.

It would be helpful if

1. the error message were improved to point to the actual problem (probably a missing gh-pages branch?)
2. the Quarto doc explicitly included the instruction to first run quarto publish gh-pages locally.

[cscheid]

As of today, the documentation includes a sentence to that matter:

Before configuring the publishing action, it’s important that you run quarto publish gh-pages locally, once.

[cboettig]

The improved docs help, but this error seems to occur on any kind of failure of the gh-pages push. It appears that the statement (_publish.yml specifying a destination required for non-interactive publish) is false -- no such file is required for gh-pages (I believe it is used for authentication in other contexts, like direct deploy to netlify or other services, (_publish.yml specifying a destination required for non-interactive publish).

If the error message is indeed erroneous in for gh-pages, it would be wonderful if quarto publish gh-pages had it's own error message for a generic failure? Apologies if I'm not following what's going wrong here, I can't seem to spot where in the source code this error message originates...

[cscheid]

@cboettig Can you point me to the repository where you're having trouble so we can look at the actions and their logs?

[mcanouil]

The message is triggered on non interactive run of the quarto publish gh-pages when the gh-pages does not exist (at least it's what I found in my many tests of the documentation and commands two weeks ago, see #5686 (comment)).

quarto create project website gh-pages
cd gh-pages
quarto render
git init
gh repo create quarto-gh-pages2 --public
git remote add origin https://github.com/mcanouil/quarto-gh-pages2.git
echo "/_site/" > .gitignore
echo "/.quarto/" >> .gitignore
git add . .gitignore
git commit -m "chore: initial commit"
git push origin main
# Add publish GHA
# Trigger GHA -> fail

quarto publish gh-pages
git push origin :gh-pages
# Trigger GHA -> success

While from documentation

[cboettig]

Thanks @cscheid ! Yup, @mcanouil example is the best minimal way to trigger this.

This morning I keep seeing this when trying to use quarto publish in a gh-action that is running inside a container. (https://github.com/eco4cast/tern4cast/actions/runs/5083003306/jobs/9133443385) It has a gh-pages branch which I can update locally in that case, but throws the same error. (I think this is because I'm failing to authenticate to github for the push, but haven't tracked down why).

[cderv]

This is indeed in fact a problem in error message and not just documentation.

From @mcanouil example (#4498 (comment)), it can be reproduce even without CI when doing --no-prompt first.

The deployment does not work because gh-pages branch is required to exist on remote called origin to allow publishing.

This is what quarto publish gh-pages is creating if it does not exist, and why it is recommended to run it first. Creating manually works too.

I'll have a PR to error more correctly for this.