The Github Workflow Connection

29. February 2024 development

Complex workflows should stay manageable and, with a clear overview, remain easy to understand even a year later — and as accessible as possible for people who are new to the project.

Encapsulating workflows into separate, single-purpose steps not only gives a better overview but also has the advantage that actions can be triggered specifically - for example, creating the current package version.

How it works

To trigger another workflow from the action, the corresponding workflow can live either in a publicly accessible repository or in the same repository where the referencing action is written.

Github Documentation for Workflows

This can look as follows:

 1name: Job that calls another workflow
 2# ...
 3
 4jobs:
 5 best-job:
 6    uses: ./.github/workflows/other-job.yml 
 7		# ...

Under uses a workflow YAML file is linked here, which is triggered when the job “best-job” is run. It’s important that the linked workflow includes a trigger for this action:

 1name: Job that is being called
 2
 3on:
 4  workflow_call:

Permissions

If the linked workflow needs permissions to run its jobs, there’s a way to pass these via a permissions attribute. Necessary secrets can also be inherited from the initial workflow - see secrets:

 1best-job:
 2    uses: ./.github/workflows/other-job.yml
 3    secrets: inherit
 4    permissions:
 5      contents: write
 6      packages: write
 7      id-token: write

Real world example

This all gets even more interesting once workflows need to run variably, depending on whether certain conditions are met. In the following example, a production deployment workflow is called when a release PR generated by release-please is merged. The output of the first job is used to reveal whether a release was successfully created in this case, triggering a deployment accordingly.

 1name: Release Please
 2on:
 3  push:
 4    branches:
 5      - main
 6
 7permissions:
 8  contents: write
 9  pull-requests: write
10  packages: write
11
12jobs:
13  release-please:
14    runs-on: ubuntu-latest
15    outputs:
16      release_created: ${{ steps.release.outputs.release_created }}
17    steps:
18      - uses: google-github-actions/release-please-action@v3
19        id: release
20        with:
21          release-type: node
22          package-name: '@sushidev-team/best-repo-ever'
23
24  prod-deploy:
25    uses: ./.github/workflows/docker-publish-prod.yml
26    needs: [release-please]
27    secrets: inherit
28    permissions:
29      contents: read
30      packages: write
31      id-token: write
32    if: ${{ needs.release-please.outputs.release_created }}