Do you have multiple projects of the same topic, whicch use the same workflows? Then you might have a look into reusable workflows.
I have multiple ansible roles and I want to use the same workflows for all of these roles. This is when reusable workflows comes into play:
Rather than copying and pasting from one workflow to another, you can make workflows reusable. You and anyone with access to the reusable workflow can then call the reusable workflow from another workflow.
This consists of two elements:
shared workflow: The actuall workflow which does all the work
caller workflow: A workflow that uses another workflow
Creating a shared workflow
Firs we are starting to create our shared workflow in a dedicate repository “github-actions-workflows”. The workflow are filed under the default path for workflows: .github/workflows/, e.g. .github/workflows/ansible-roles-release.yml. In my case the workflow will do some linting, release preparation, creating and publishing the release (ansible role).
As you can see there are two important things:
the workflow will be triggered on [workflow_call]
the workflow defines secrets (but also could define inputs)
the secrets are reference accordingly in the steps like api_key: ${{ secrets.galaxy_api_key }}
Workflows that call reusable workflows in the same organization or enterprise can use the inherit keyword to implicitly pass the secrets.
Caller Workflow
In the repositroy where you want to run the reusable workflow, you have to add the calling workflow under .github/workflows/, e.g. .github/workflows/ansible-roles-release.yml.
As part of the jobs you have to add call-workflow-passing-data.uses, which refers to the workflow which as to run, which is my ansible-roles-release.yaml on main-branch. I also pass the required secrets under secrets. Important is that these secrets (e.g GITHUB_TOKEN) are defined in the repository where the caller workflow is.
That’s all, pretty simple isn’t it, and indeed very helpful. However, keep in mind, there are certain limitations:
You can call a maximum of 20 reusable workflows from a single workflow file. This limit includes any trees of nested reusable workflows that may be called starting from your top-level caller workflow file.
For example, top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml counts as 2 reusable workflows.
Any environment variables set in an env context defined at the workflow level in the caller workflow are not propagated to the called workflow. For more information, see “Variables” and “Contexts.”
To reuse variables in multiple workflows, set them at the organization, repository, or environment levels and reference them using the vars context. For more information see “Variables” and “Contexts.”
Workflow publisher
In order to deploy the caller workflow to all the repositories, I also use a workflow publisher, which is stored under .github/workflows/workflow-publisher.yml of the repository “github-actions-workflows”. This job runs when changes are made to the calling workflow.