How to use the GitHub Actions `workflow_run` event?

Another frequently-requested feature for Actions is a way to trigger one workflow based on the completion of another workflow. For example, you may want to take the results of a CI workflow and run some further analysis.

The new workflow_run event enables you to trigger a new workflow when one or more workflows are requested or completed. Runs triggered by the workflow_run event always use the default branch for the repository, and have access to a read/write token as well as secrets. As an example, as a maintainer you could set up a workflow that takes the artifacts generated by the pull request workflow, do some analysis, and post comments back to the pull request. This event is also available as a webhook and works all repos.

This is quoted from Github's blog.

Could anybody tell me how to implement the example proposed using the new event workflow_run? The documentation only provide a very simple example:

on:
  workflow_run:
    workflows: ["Run Tests"]
    branches: [main]
    types: 
      - completed
      - requested

I would be very glad if someone can teach me how to achieve the example.

To get the example to work (i.e. to have one workflow wait for another to complete) you need two files. Both files live in the .github/workflows folder of a repository.

The first file would be set up as usual. This file will be triggered by whatever event(s) are set in the on section:

---
name: Preflight

on:
  - pull_request
  - push

jobs:
  preflight-job:
    name: Preflight Step
    runs-on: ubuntu-latest
    steps:
      - run: env

The second file states that it should only trigger on the workflow_run event for any workflows with the name Preflight and must be on your repository's default branch, usually main or master:

---
name: Test

on:
  workflow_run:
    workflows:
      - Preflight
    types:
      - completed

jobs:
  test-job:
    name: Test Step
    runs-on: ubuntu-latest
    steps:
      - run: env

This more-or-less the same as the example from the GitHub Actions manual.

As you can see on the actions page of my example repo, the Preflight workflow will run first. After it has completed, the Test workflow will be triggered:

When you try this out, you will find that the Test workflow always runs the code and workflow configuration on your default branch, usually main or master.

This is because, (quoting from the manual):

This event will only trigger a workflow run if the workflow file is on the default branch.

This means you'll need to develop workflows triggered by workflow_run on your default branch, which is a little unfortunate.

This also means that if you need the "Test" workflow to run against the code of your branch or pull request, then you'll need to do more work as described below:

Every actions is run with a set of contexts. The github context holds information about the event that triggered the workflow. This includes the branch that the event was originally triggered from/for: github.event.workflow_run.head_branch.

This can be used to check out the origination branch in the action, using the actions/checkout action provided by GitHub.

To do this, the Yaml would be:

---
name: Test

on:
  workflow_run:
    workflows:
      - Preflight
    types:
      - completed

jobs:
  test-job:
    name: Test Step
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          repository: '${{ github.event.workflow_run.head_repository.full_name }}'
          ref: ${{ github.event.workflow_run.head_branch }}
      - run: git branch
      - run: env