Add option publish-gh-pages-branch

[felixfontein]

I've tried integrating updating GH Pages into the shared workflow (_shared-docs-build-publish-gh-pages.yml), and after some tries it seems to work. This PR adds a new option, publish-gh-pages-branch, which needs to be explicitly enabled like this: ansible-collections/community.hrobot@933f952 (obviously without pointing to the workflow in my branch once this is merged ;) )

Successful run: https://github.com/ansible-collections/community.hrobot/actions/runs/9702624870. That run made https://ansible-collections.github.io/community.hrobot/pr/114/firewall_module.html#synopsis show Test! as the last paragraph of the Description (before it was test).

I'm not sure whether this is the best solution, and I'm also a bit surprised that not having environment: github-pages there works. (I had it in the shared workflow first, that made it fail.)

[briantist]

This mostly looks good to me. I'm wondering why we would default the option to false though since the previous behavior for anyone using this workflow would be to publish. If we default to true then we don't need every collection to update, and I think it's also the more intuitive option, no?
(we could also change the option to skip-publish-gh-pages or similar and default to false for the same effect)

[felixfontein]

The main reason for the default false is that additional permissions are needed. If these aren't present, then the workflow will start failing (which among others mean: CI is always failing in PRs). If this isn't merged, then the workflow will effectively stop working since the gh-pages branch is no longer taken as the source for GH Pages, but the workflow won't fail.

Also: it could (theoretically) be that some user of this workflow already implemented the gh-pages branch to GH Pages update in another way - for them this would be a breaking change.

[briantist]

Good points, thanks!

[felixfontein]

Thanks for reviewing this!

[felixfontein]

Hmm, maybe that argument wasn't right, since without adjustment the docs workflows now also fail: https://github.com/ansible-collections/community.sops/actions/runs/9725081312

The workflow is not valid. .github/workflows/docs-pr.yml (Line: 36, Col: 3): Error calling workflow 'ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main'. The nested job 'publish-gh-pages' is requesting 'pages: write, id-token: write', but is only allowed 'pages: none, id-token: none'.

[gardar]

Hmm, maybe that argument wasn't right, since without adjustment the docs workflows now also fail: https://github.com/ansible-collections/community.sops/actions/runs/9725081312

The workflow is not valid. .github/workflows/docs-pr.yml (Line: 36, Col: 3): Error calling workflow 'ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main'. The nested job 'publish-gh-pages' is requesting 'pages: write, id-token: write', but is only allowed 'pages: none, id-token: none'.

Yep, also noticed this happening here: https://github.com/prometheus-community/ansible/actions/runs/9740090100
So this is actually a breaking change.