Get artifacts from triggering workflow via workflow_run event

In one of my repos, I decided that I wanted to store notebooks as markdown, without outputs, for diff/version control reasons. The notebooks would be executed when the docs are built.

Up to this point, I was hosting the docs on ReadTheDocs, but because the notebooks are training neural networks, it was crashing their workers. So I decided to build the notebooks in GHA and deploy my docs using Pages instead :slight_smile: I was able to set up a workflow that does just that, until I got a PR from a fork.

In hindsight, it should have been obvious, but for security reasons a workflow triggered from a fork cannot push directly to the repository.

The solution I was thinking of is something like this:

  • PR/fork builds the docs and puts them into an artifact. They could in theory inject whatever they want into that artifact, but they can’t push it anywhere.
  • A separate workflow that exists in the main or docs branch is triggered by completion of the previous workflow (i.e. the PR/fork cannot edit this workflow, only trigger it). This second workflow downloads the artifact and pushes it to the docs branch.

I think this should be possible using a worklow_run event, but it’s unclear to me how the second workflow can inspect the triggering workflow to find the artifacts.

Can I get some input on this general approach, or specifically how to get the artifacts from within the second workflow? Thanks!

The first example in this blog post (ReceivePR.yml and CommentPR.yml) is an example of one workflow creating an artifact, and the next one (using workflow_run) retrieving it:

However, I’m confused why you want to publish docs generated from a PR. Shouldn’t that wait until the PR has been approved and merged? :thinking: In particular, the generated docs will still show up on your GH Pages site, so if anyone puts anything bad in there, it’ll likely be ascribed to you.

This is similar to RTD’s preview PR feature: Preview Documentation from Pull Requests — Read the Docs 5.19.0 documentation

Anyways, this is what I landed on: GitHub - adriangb/gh-pages-docs: See the docs at https://www.adriangb.com/gh-pages-docs/

1 Like

Thanks for the explanation, and sharing your solution! :slightly_smiling_face:

Yeah, thanks for sharing! Personally, I find GitHub Pages too limited for documentation previews. Netlify does a better job at that, but if you exceed the free plan then it gets costly.

Interesting, I haven’t tried them for FOSS Python libraries. Would you happen to have a link to a guide for this specific application?

We use it at work, but I don’t have access to the Netlify configuration, unfortunately. The setup is basically to use site builds with a Git repo as the source. The main branch is considered to be “production” and deploy previews are enabled to build the documentation for PRs. They have a good GitHub integration, the deploy preview shows up in PRs as a check, with a link to the site it built. Each preview is independent and remains available “forever”. The costly part is the build minutes, you get 300 minutes/month for free with the starter plan, after that it’s $7 per 500 minutes. And you only get a single concurrent build on that plan. GitHub on the other hand offers unlimited build minutes, but GitHub Pages doesn’t support hosting independent sites and the total size is limited to 1 GB.