A publish target for GitHub Pages

[briantist]

GH Pages might be a nice target for publishing, as it'd be (theoretically) available to any collection without an external service. Since publishing primarily involves commits, it could be done completely within the actions ecosystem, though I know folks can be quite wary of automation committing to a repository.

Some things to think about are how to handle publishing for different PRs (sub-directories?), commit bloat (does this matter?), support for publishing in separate repositories (will require a PAT).

[briantist]

Having looked into this a little bit, I don't think we'd need a shared workflow for this, because there are two existing actions that both seem to be able to handle the entire publishing step. At best, we might wrap it into a composite action that takes inputs and handles some light logic around pathing for where to publish PRs. But we might be able to get away with only a sample/example.

The existing actions are:

• https://github.com/peaceiris/actions-gh-pages
• https://github.com/JamesIves/github-pages-deploy-action

Re: "commit bloat": both of the actions above support an option that doesn't keep building up commits (basically a force-push I suppose)
Re: "directory target" (for publishing different versions to the same site), both actions support a destination directory, though this may require some careful consideration or additional logic, for us to be able to publish individual builds while not deleting or affecting existing builds in other directories.
Re: "publishing in other repos": both actions support publishing in other repositories, either via a PAT, a deployment key, or both, so we're well-covered there too.

[felixfontein]

I would never use force push in a collection repo - at least not in the main branch, or in any of the stable branches. (Actually policy forbids this for the repos inside github.com/ansible-collections anyway.) I would guess publishing into another repo (specifically for docs) makes most sense.

[briantist]

I should clarify, GitHub pages usually works off of a dedicated branch, which (generally, unless your entire repo is just for pages), does not actually "branch" off the rest of it and only contains docs content. The "typical"/default name of this branch is gh-pages but it is customizable. It is possible to use a subdirectory within a branch as the publish source, but I would not recommend that, especially not with force pushing.

A separate repo is certainly possible, but I personally think it would be ok (and easier) to have a dedicated branch in a repo for this. That keeps everything within the collection repository, and it removes the need for a separately maintained PAT or deploy key that needs to be shared with the source repository.

The force-push/single-commit option is also not required, and I suppose for most repos the "extra" commits would not be negligible.

Being able to set this up self-contained within a single collection makes GH pages likely the least friction option for most collections, and could be initialized easily (still optionally!) during collection creation, so I think it may end up being the best and most widely adopted option.

But very happy to have this open and see where discussion leads. Opinions from you and other maintainers are vitally important!