Turning off clean and usingtarget-folder will probably be enough (I'd suggest looking at the README for more details on what these options do).

Keep in mind if the people making the pull requests don't have the required permissions it will throw a permission related error as they may not have access to the tokens it needs to make the requests.

I'm genuinely interested in ways to include generated docs in a review process.

One idea I had was for automation to maintain PRs on thegh-pages branch.

That's orthogonal to having a staging site. Though, they share a common problem around finding the right base version of the docs to do a PR for.

I think in addition to using atarget-folder like James mentioned, just adding.previews to theclean-exclude option would do the trick.

The automation around pruning previews when closing PRs is interesting.

I guess none of these steps are actually part of the action. And, handling permissions is gonna be a challenge.

I'd totally dig having documentation on best practices, though.

Thank you@JamesIves and@Pike for quick responses and ideas.

It looks possible to implement the feature using the parameters and the flow you mentioned. One thing remains unclear to me deleting previews of merged PRs as@Pike pointed. I may implement this behaviour with another action likehttps://github.com/marketplace/actions/remove-file

For my repository as temporary solution I enabled Netlify integration, it provides deploy previews but 300 min/month limit for free plan can be a bottleneck.

It's been a while, but let me pick up this discussion. I'm currently writing an action to do exactly what is described here. And I'm worried that I'm replicating what is already available in this action. And whatever I'm not replicating will be missing in the end.

So maybe it's better to extend this action with missing functionality?

There is one puzzle piece missing in the description so far.

• We need to be able to push to target_directories likepr-42. Preferably clean.
• We need to be able to delete such directories.
• We need to maintain aversions.txt file

That last one is new, so let me explain it:
versions.txt (or similar) contains all the versions I'm pushing from PRs, branches, tags etc.
This allows me to implement a version picker on the website. Just a little JavaScript which will load said file and present it as links to the other versions.

Current workarounds (not verified):

• Don't do clean deployments
• Use two commits. One for the target_directory and one for the versions file.