Remove usage of peaceiris/actions-gh-pages action

[felixfontein]

Since the https://github.com/peaceiris/actions-gh-pages action isn't really actively maintained anymore (many Dependabot PRs open for many months already, still using Node 20 despite issue and PR to fix it available for > 1 month), and wasn't that actively maintained in the past either, I looked into whether we could replace it by some tasks.

Since right now it's basically only used to modify the gh-pages branch by adding/replacing/removing directories (with all their content), I think this should be possible.

I'd like to test this a bit before merging, so I'm marking this as a draft for now.

[felixfontein]

• Push to main with no docs changes: https://github.com/felixfontein/ansible-acme/actions/runs/24965625359/job/73099833063
• PR opened with docs changes: https://github.com/felixfontein/ansible-acme/actions/runs/24965729028/job/73100182344?pr=111 -> felixfontein/ansible-acme@48616e2
• PR closed: https://github.com/felixfontein/ansible-acme/actions/runs/24965831877/job/73100378443 -> felixfontein/ansible-acme@35ac9f5
• Plugin rename (so filenames change) in PR: https://github.com/felixfontein/ansible-acme/actions/runs/24966099547/job/73101116231 -> felixfontein/ansible-acme@99f4886

Seems to work as expected.

[briantist]

I think this looks good to me for moving away from this action.

I mistakenly thought we were using force_orphan=true to keep commit bloat down but I forgot that it does not work with keep_files=true.

It might be nice to implement that ourselves later.

Essentially, that option pushes every commit as the first commit of the branch, rewriting its history, which helps to keep the size down, but it sounds tricky to implement when a given workflow is meant to be acting on a single branch/pr/commit but also has to include all the rest of the repo contents to do that correctly, maybe not worth the effort.

Thanks for your work on this as always @felixfontein

[felixfontein]

I mistakenly thought we were using force_orphan=true to keep commit bloat down but I forgot that it does not work with keep_files=true.

It might be nice to implement that ourselves later.

Essentially, that option pushes every commit as the first commit of the branch, rewriting its history, which helps to keep the size down, but it sounds tricky to implement when a given workflow is meant to be acting on a single branch/pr/commit but also has to include all the rest of the repo contents to do that correctly, maybe not worth the effort.

That sounds like a great idea, but I don't think it should be enabled by default. I guess we could make it a configuration option. (In any case, I think this would be best as a follow-up, for later.)

[briantist]

That sounds like a great idea, but I don't think it should be enabled by default. I guess we could make it a configuration option. (In any case, I think this would be best as a follow-up, for later.)

In theory, with the "new" (2+ year old) purely actions-based workflow for GH pages, we should be able to completely avoid having a branch and committing contents at all, but that process is missing features that would support what we're doing here, and the team has declined to implement any of them, see:

• Deploy website to custom url route actions/deploy-pages#73 (comment)
• Download pages artifact actions/upload-pages-artifact#57

This is a possible workaround by using the cache as a replacement for not being able to download the site artifact:

• Download pages artifact actions/upload-pages-artifact#57 (comment)

[felixfontein]

Being able to download the current page would definitely be great... One of the reasons why I didn't introduce this action for example to community.general is because I'm scared the gh-pages branch will flood the repository's space limits and basically prevent working on the collection. (The collection is pretty big, which also means that building the docs is slow - that was reason no. 2 :) But even if it would just run nightly, the amount of space this would eat up - especially with multiple branches or even tags - is considerable. I also thought about storing the result in a second repository, but I never got around to implement that. Also due to the space requirements it might still cause other problems for the ansible-collections org in total...)

Using caches for this is very dangerous: caches are ephemeral and can be deleted at any point in time (because the user expliictly tells GitHub to do so without realizing what it means for the pages build, or because GitHub decides it wants to save some disk space). Using them for mission-critical data is a bad idea.

[felixfontein]

@briantist thanks for reviewing!

[briantist]

My CI is failing now: https://github.com/ansible-collections/community.hashi_vault/actions/runs/25253040128/job/74048023586

It's the delete that fails but that seems to be caused by the if: inputs.publish-gh-pages-branch conditional not being included on the new steps that rely on the checkout.

Also we were using the github action for inputs.action == "teardown" not just for "publish" and it looks like we may have broken that functionality since we no longer have any steps that remove.

Sorry I should have caught these earlier in review @felixfontein

[felixfontein]

I'll create a PR to fix this.

Also we were using the github action for inputs.action == "teardown" not just for "publish" and it looks like we may have broken that functionality since we no longer have any steps that remove.

That does work (I tested that), since Remove target directory from checkout deletes the data for both teardown and publish, and only for publish it's replaced by the new version of the docs.