GitHub Actions: Trigger a workflow with workflow_dispatch

Scenario & Requirements Link to heading

  1. We have a part of our application in one repository, called web-application.
  2. This web-application repository has several workflows of its own - including a workflow called build that packages the application, and uploads it to a registry.
  3. We have a separate repository that includes integration and end-to-end tests for this application, called web-application-tests.
  4. web-application-tests contains a workflow called tests that runs the relevant tests on the most recently built image.
  5. We want to also be able to run the tests workflow periodically or trigger it manually.

Objective: Whenever the build workflow of the web-application repository finishes, we want to trigger the tests workflow from the other repository using the workflow_dispatch trigger.

Solution overview Link to heading

Our main requirement is that the tests workflow need to run after the build workflow. We wish to maintain the separation of the repositories, due to for example different dependencies required by an application and the testing framework(s). Therefore we need to insert a trigger at the end of the build workflow to start the tests workflow.

In order to be able to create the workflow_dispatch trigger event in the web-application-tests repository, the web-application repository and the build workflow need to have a separately created GitHub Personal Access Token (PAT) - as by default, the token given by GitHub to a workflow is always scoped to just the repository that contains the workflow.

In total, we then need to configure 3 things:

  1. Create a PAT with the right scope, and add it as a GitHub Actions secret to the web-application repository.
  2. Add a trigger step to the build workflow to launch the tests workflow with the right inputs.
  3. Add workflow_dispatch as a trigger to tests workflow.

Solution details Link to heading

Create a PAT Link to heading

Follow the instructions here, and make sure to tick “repo” for permissions. If you are working within a GitHub organization that uses SAML, click “Enable SSO” as shown in the instructions in steps 9 and 10.

Copy the value of the token and save it as a GitHub Actions secret for your repository, with the name WORKFLOW_DISPATCH_PAT.

Creating a workflow_dispatch event within thebuild workflow Link to heading

Using the abridged snippet from below as a guideline, make sure you configure:

  1. BUILT_IMAGE_NAME as an environment variable in the build stage - you need to tell the tests workflow what image to test.
  2. Replace REPO_OWNER, REPO_NAME and WORKFLOW_FILENAME with your respective values in the URL of the curl command
  3. Replace TARGET_BRANCH of the curl payload with the target branch of the repository that you are calling
name: "build"
... # triggers of the build workflow
  build: # job to build the image
    needs: build # only run 'trigger-tests' after 'build' is complete 
      - name: Trigger 'tests'
          # important - we must tell the tests workflow what image to test
          # this environment variable should be set by the 'build' job
          image_to_test: "${{ env.BUILT_IMAGE_NAME }}" 
        run: |
          curl -XPOST \
            -H 'Authorization:token ${{ secrets.WORKFLOW_DISPATCH_PAT }}' \
            -H "Content-Type:application/json" \
            -H "Accept:application/vnd.github" \
  {REPO_OWNER}/{REPO_NAME}}/actions/workflows/{WORKFLOW_FILENAME}.yml/dispatches \
            --data '{"ref": "{TARGET_BRANCH}", "inputs": {"image_to_test":"${{env.image_to_test}}"}}'          

Receiving the workflow_dispatch trigger within the tests workflow Link to heading

The tests workflow primarily just needs the required trigger to be included, as shown below. Make sure to use the input value in later parts of the workflow with ${{ inputs.image_to_test }}.

name: "tests"
        type: string
        description: container image to test
        required: true
      - name: "run tests"
        run: run_tests_for_image ${{ inputs.image_to_test }}

References Link to heading