Fix docs publication workflow

[jessestorbeck]

Following up on my conversation with @jkhartshorne about publish-docs.yml:

Thinking about this a bit more, it turns out that we can't just push site updates any time we merge changes to /docs into main. The reason is that if the docs updates accompany changes to any packages/templates, there may be a delay between when the changes are merged into main and when the new packages are actually published, e.g. currently, we have a number of new, unpublished docs updates in main, but new packages won't publish until we merge #306. Conversely, there will be docs updates that don't involve changes to packages, e.g. typo fixes.

The situations where we want to update the docs are then:

• Merges into main affecting /docs but not affecting /packages or /templates
  • Even this is potentially too broad if the docs changes relate to a merged but yet-to-be-released package update (i.e. additional docs changes were deemed necessary after the original PR was merged, but before the changesets PR was merged).
  • Or if we were in a situation like we are currently (building up updates on main before doing a round of package releases), and someone made a PR to fix a random typo in the docs, we'd have to wait to merge their PR until packages had been released.
• On publication of packages when the package update was accompanied by docs updates.
  • This seems kind of hard to know based on how the changesets action works.
  • However, it doesn't seem like it would hurt anything to just republish the docs after every round of package releases, even if there aren't any actual docs updates.

I think this is feasible as an GitHub Action that covers most cases, but it won't be perfect. Alternatively, if we want to push docs updates manually, I don't think it should be a workflow at all. For our purposes, a package script at the top level of the repo would be simpler and allow us to keep the branch protection we already have in place.

[jodeleeuw]

FYI, we recently added an action to publish docs to the jspsych repo and were thinking of exactly the same problems. Ended up making it a manual deploy action for now. You can launch a job manually on GitHub actions if you configure that as an option.

[jessestorbeck]

Thanks, @jodeleeuw -- I've basically copied your workflow, but I ran into some snags. When we set up mike, I thought it was a good idea to restrict who can push to gh-pages. This was mostly because it seemed too easy for someone testing site updates to accidentally push their mike commits.

As far as I've been able to tell, there's not a good way to have the workflow inherit the git permissions of the person triggering it. Changing the git config did not work -- it takes the permissions from GITHUB_TOKEN instead. It also seems not possible to restrict who in an org can run particular workflows.

If it's going to be manually triggered and we want to keep the branch protection, my thinking was that the easiest solution would be to make another package script that could only be run by senior team members who had push permissions for gh-pages.