Publish action failing due to _publish.yml

[kellyatkinson]

I'm using these actions to publish a Quarto book. I am constantly getting an error message via email after the actions fire, with details as below.
Seems to want _publish.yml somewhere instead of publish.yml? Also my email settings for Git are already correctly set so I'm unsure where that line is coming from, and whether I need to adjust it.

[cscheid]

Also my email settings for Git are already correctly set so I'm unsure where that line is coming from, and whether I need to adjust it.

Your email settings for git are different than those that are used by GitHub Actions. That line you're seeing is the GHA script so that if your github actions need to push to the repository, you will see that email. No action is needed on your part.

Seems to want _publish.yml somewhere instead of publish.yml?

I apologize, I'm confused. Why do you think publish.yml is the right file name? The name of the file that has information needed for quarto to publish to different services is _publish.yml.

[kellyatkinson]

The name of the file that has information needed for quarto to publish to different services is _publish.yml.

Thanks for clarifying this. After I filed the issue, I read further in the Quarto docs and saw the reference to the _publish.yml file. My confusion here is from my publishing path: I have my book code in a GitHub repo and am choosing to publish to GitHub Pages with CI using these actions. As such, the _publish.yml file wasn't created at any step during my publication process to date.

From the Quarto documentation on Quarto Pub I see _publish.yml being used when publishing to Quarto Pub but not for publishing on Github Pages, where this particular filename is never referenced as part of the process.

I've now published a version of my book to Quarto Pub in an effort to have the _publish.yml file created, but this is a footprint I don't want for my book. How should the _publish.yml file be populated when publishing to GitHub Pages? If it's not required for this publication path, why is the GitHub Action erroring on requiring this file?

[cscheid]

I think this is a combination of two issues.

1. there are separate files publish.yml (the github action workflow description referenced sometimes in our documentation) and _publish.yml, the file created by quarto publish that stores metadata needed by some services.

2. From my understanding, you shouldn't need a _publish.yml for gh-pages. Can you share your github action workflow? Is it possible that you haven't added the target: gh-pages option to the publish action options? See this workflow for an example of the syntax

[kellyatkinson]

Thanks, @cscheid. I think the confusion is stemming from one difference:

• When doing the initial publication to Github Pages the instructions (in Render to docs) specify to publish from the docs directory of the main branch:

Your site will also be updated whenever you commit and push to main.

• Then, a couple of lines later on the same page (in Publish Command), the instructions for publishing indicate that the source should be set to the gh-pages branch:

Before attempting to publish you should ensure that the Source branch for your repository is gh-pages and that the site directory is set to the repository root (/).

I don't adequately understand why the change in branch is necessary. If the CI action is publishing from the gh-pages branch then why are the initial instructions to publish from the main branch? When going from one set of instructions to the other, I don't even have a gh-pages branch yet. Why do I need to use this separate branch?

[cscheid]

Then, a couple of lines later on the same page (in Publish Command)

Ok, I see. Note that those two sentences are in different sections. One section is "Render to docs", and the other section is "Publish Command". The introduction of that page says:

There are three ways to publish Quarto websites and documents to GitHub Pages:

1. Render sites on your local machine to the docs directory, check the rendered site into GitHub, and then configure your GitHub repo to publish from the docs directory.
2. Use the quarto publish command to publish content rendered on your local machine.
3. Use a GitHub Action to automatically render your files (a single Quarto document or a Quarto project) and publish the resulting content whenever you push a source code change to your repository.

So those are there to mean totally different ways to publish to gh-pages; you can pick any one of them.

[cboettig]

@cscheid Just to follow up on this, the error shown above,

Error: no _publish.yml file is available

Is precisely the error a user of the GitHub Actions + gh-pages mechanism will see if they overlook this manual instructions:

Before attempting to use quarto publish (either locally or from a GitHub Action) you should be sure to configure the Source Branch

and do not have a gh-pages branch. In this case, the error is erroneous and misleading.

Is it possible to either have the gh-action seek to throw a more informative error like:

this repository does not get have a gh-pages branch on GitHub.  Please create one first by doing...

instead? Or better yet, is it possible for the gh-Action to automate this process? (Not sure if the defautl GITHUB_TOKEN can create branches and configure the source branch, but certainly that would be preferable to the manual option).

Maybe adding a Comment line in the gh-actions Action template noting that users should manually create the gh-pages branch would help too; it's easy to miss in the documentation given how things are laid out there with so many different options....

Lemme know if it would help to open a new issue for this.

[cscheid]

@cboettig I hear you, and I agree our documentation here isn't great.

(@cwickham I know you have a full plate, but quarto-actions is definitely a place with a combination of high complexity, error-proneness and documentation issues. I wonder if it would make sense for us to redesign these docs in the future, and combine them better with the publishing documentation on quarto.org)

[cwickham]

@cscheid I'm adding this to my list of things that could use attention.