The instructions on using GitHub Pages to publish docs are outdated and will stop working on June 30th

[felixfontein]

The way setting up GH pages publishing is described on https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages#enabling-pages is outdated and will stop working on June 30th, according to https://www.josephguadagno.net/2024/04/03/migrate-to-github-actions-from-pages-legacy-worker. Despite the mention of Jekyll all over that blog post this also affects publishing raw HTML pages (as used by the shared workflows from this repo).

Fixing this is probably quite easy, you simply need to add a workflow to the main branch that handles pushes to the gh-pages branch and publishes them (look for Static HTML Workflow Template in the blog post). I'll try this out later or tomorrow and will report back here how it went.

Ref: https://github.com/ansible-community/ansible-build-data/issues/416

[felixfontein]

UPDATE: See https://github.com/ansible-community/github-docs-build/issues/92#issuecomment-2198238661 for how to fix this.

Actually fixing this is very simple:

1. Go to the repo's settings, the GitHub Pages tab, and change "Build and deployment"'s "Source" from "Deploy from a branch" to "GitHub Actions".
2. Create a commit similar to https://github.com/ansible-collections/community.crypto/commit/06c976e3f9d26c25aa2c2f2629ac6db78cb53db2 in the gh-pages branch (adjust the URL in line 26 of the workflow!) and push it.

[samccann]

So along with the wiki needing updates, we also need to update the shared workflow, right? - https://github.com/ansible-community/github-docs-build/blob/main/.github/workflows/_shared-docs-build-publish-gh-pages.yml

[webknjaz]

@samccann using shared workflow would be a bit more tricky — all the callers would have to set up the correct privileges as well.

[felixfontein]

No change at is needed to the shared workflow. (The Wiki should be updated though.)

[felixfontein]

Hmm, something isn't working correctly yet. When creating a PR or updating it, the docs workflow updates the gh-pages branch (as before). But for some reason the push trigger for the gh-pages branch doesn't trigger the workflow in that case.

(Test cases: https://github.com/ansible-collections/community.hrobot/pull/114, https://github.com/felixfontein/ansible-acme/pull/80 - in both cases the gh-pages branch has been pushed to, but the GH Pages update workflow isn't triggered. In the community.hrobot repo I even added the workflow to the main branch as well, in case that makes a difference, but same result...)

(https://github.com/ansible-collections/community.hrobot/blob/gh-pages/.github/workflows/deploy-gh-pages.yml / https://github.com/ansible-collections/community.hrobot/blob/main/.github/workflows/deploy-gh-pages.yml)

[briantist]

But for some reason the push trigger for the gh-pages branch doesn't trigger the workflow in that case.

I believe this is expected, events that trigger workflows do not trigger them when the thing was initiated by a workflow, to prevent infinite loops. It's tied to the token, you have to use a PAT to cause those events to trigger workflows normally.

This might be something we could instead use the workflow_run trigger for: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run

I haven't looked closely at what's been done so far though, I've been AFK for most of the week, and have very little time available, apologies.

[felixfontein]

I might have figured out a way to do it: https://github.com/ansible-community/github-docs-build/pull/93 That doesn't require to have the workflow in the gh-pages branch (or in main), but only a small modification of the repository's docs PR/push workflows that call the shared workflows.

[felixfontein]

Ok, now that #93 is merged, you can (and actually have to, due to an unexpected side-effect: https://github.com/ansible-community/github-docs-build/pull/93#issuecomment-2198230542) update the workflows in your repository as here: https://github.com/ansible-collections/community.sops/commit/03d53d08942161491df294ad68bf275abacc5363

EDIT: You still need to do: Go to the repo's settings, the GitHub Pages tab, and change "Build and deployment"'s "Source" from "Deploy from a branch" to "GitHub Actions".

Adding the workflow to the gh-pages branch as described in https://github.com/ansible-community/github-docs-build/issues/92#issuecomment-2192468312 is not necessary.