Improve examplary YAML file and correct typos

[jakobarendt]

For GitHub pages, the publish action needs write access to the contents of the repository. This can be achieved via changing the settings for actions workflows in the repository's settings from the default read only to write. However, this change in settings then holds for all workflow YAML-files of the repository.

Alternatively, one can set such permissions for each job in the workflow YAML-files individually. For the examplary YAML file, I propose this approach, as it prevents giving permissions to other GitHub Actions workflow jobs unintendedly. Additionally, I modify the documentation to account for the change in the examplary workflow YAML-file.

The second commit records some changes to the main README.md that correct typos and improve relative links.

Cheers,
Jakob

[cderv]

Thanks a lot @jakobarendt .

Is this permissions setting to be required in the YAML workflow file new ?

I was sure this was working without it. Can we link to a blog post or related doc on this ? This is Github specific and it would help to send users to the correct reference so that they know what they are configuring.

Thank you

[jakobarendt]

Yes, to my knowledge, a permission is required when using the Quarto publish action for GitHub Pages – either with a job-specific permission in the YAML workflow file itself (my suggestion) or with a write permission in the repository's setting that would then apply to all of its YAML workflow files.

To be honest, I have not (yet) published anything on the topic. I basically discovered it while debugging unsuccessful workflow runs during the setup of my master's thesis repo. The corresponding log file of the run, after which I accounted for all other potential sources of failure, gave (at least to me) an indication in L62 and L63 that it is an issue of unsufficient permissions:

remote: Permission to jakobarendt/mathesis-depop.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/jakobarendt/mathesis-depop/': The requested URL returned error: 403

To me, this need for a write permission also seems intuitive as the workflow run needs to render and commit the content files to the gh-pages branch underlying the GitHub Page – otherwise, I do not see how the published website could reflect any changes in the content of the .qmd files.

[jakobarendt]

@mcanouil and @t-kalinowski might be good reviewers for my suggestions since they contributed to the guide page about publishing with GitHub pages. On the guide page, the examplary YAMLs already contain the changes that I propose.

@mcanouil wrote a paragraph about setting permissions in the repository's settings and @t-kalinowski specifically added the permissions to the examplary YAMLs.

[mcanouil]

To check more thoroughly the required permissions, we can use https://github.com/GitHubSecurityLab/actions-permissions.

To note, Quarto documentation on publishing to GitHub Pages needs some update, see:

• gh-actions documentation issues quarto-cli#5686.
• GHA to Github Pages: misleading error + need for documentation quarto-cli#4498.

[mcanouil]

The related "epic":

• GitHub Pages Docs quarto-cli#6204

[mcanouil]

@jakobarendt we'll review this in parallel to as we'll work on the documentation to have consistency.
Thanks again for the PR.

[cderv]

Thank you