Stdpopsim: "build and deploy docs" workflow errors on personal fork

[andrewkern]

the build and deploy docs workflow is throwing an error on my fork of master. it reports:

Input required and not supplied: token

i'm guessing this has to do with permissions to access secrets.POPSIMBOT_STDPOPSIM_DOCS_TOKEN
as mentioned in .github/workflows/docs.yml but I'm unclear as to how to fix things.

[jeromekelleher]

Can you give a link to the PR/the failing build please? I'm not sure you'd expect the actions to work if it's just building on your own fork and not in the context of the upstream repo

[andrewkern]

it's just from pushing updates from master to my fork. no new code.

https://github.com/andrewkern/stdpopsim/actions/runs/334249380

[jashapiro]

Yeah, that's going to fail on a fork unless you have a POPSIMBOT_STDPOPSIM_DOCS_TOKEN secret set for yourself. I assume those don't get passed to forks, even when set in the base repo (to do otherwise would seem madness; Update: confirmed, GH is correctly not copying secrets willy-nilly). So I think you may have to go to the repo settings and define it yourself. Should be at https://github.com/andrewkern/stdpopsim/settings/secrets

You will presumably want to generate a new one for this repo/purpose with only the necessary permissions: https://github.com/settings/tokens/new

All of this assumes you actually want the actions to run in your fork. If you don't, the GHA can be modified to only run in the popsim-consortium/stdpopsim repo, which seems like it might be the right move for most cases. Individuals can then enable the action for their own repo, setting up the necessary secrets intentionally, rather than being surprised by errors when they do innocuous things to their own fork.

[andrewkern]

thanks @jashapiro! i agree this should probably only run in popsim-consortium/stdpopsim by default. do you know how we can make this change?

[jashapiro]

I may have spoken too soon. I can't find an obvious way to restrict the action as a whole to a particular repo. I can imagine doing it with if: github.repository_owner == 'popsim-consortium' statements at each step, but that seems like it would probably not be ideal. There may well be a more universal way to handle it.

[grahamgower]

We certainly don't want forks uploading docs previews to the stdpopsim-docs repository. Currently they can't, because they won't have a POPSIMBOT_STDPOPSIM_DOCS_TOKEN secret set that works with @PopSim-bot. But the errors are definitely annoying and possibly disconcerting to someone that just wants to submit a pull request.

I don't see a perfect solution here (there's no option in the popsim-consortium repository to disable this for forks). @andrewkern, you can disable running workflow actions under the settings within your fork. Of course, this means that everyone that forks the repository needs to disable this!

Probably we should also do what @jashapiro suggests, and protect the docs job with an if statement. Pinging @benjeffery here, in case he has any other ideas (and because tskit/msprime repositories will have this issue too).

[benjeffery]

You can still build the docs on the fork, just not push it. My proposal for a fix is at: https://github.com/tskit-dev/tskit/pull/947

[benjeffery]

I'm intending to package up this docs workflow (and others) as a reusable action - so eventually we won't need to duplicate fixes/features like this across repos.