Reusing Workflows in GitHub Actions

GitHub Actions is a powerful tool for automating CI/CD processes, and one of its most valuable features is the ability to reuse workflows. This functionality helps prevent code duplication and allows you to streamline automation across multiple repositories and projects. In this article, we’ll explore how to reuse workflows effectively, saving time and maintaining consistency in your development pipelines.

Overview

Reusing workflows means you can avoid copying and pasting the same workflow logic across multiple repositories. Instead, you can reference existing workflows, reducing duplication of code. This makes workflows easier to maintain and enables faster development, as you can build on previously created workflows, much like how you use actions in GitHub Actions.

Reusing workflows also promotes best practices by encouraging the use of well-designed, tested, and proven workflows. Organizations can establish a library of reusable workflows that can be centrally maintained, ensuring consistency across projects.

Accessing Reusable Workflows

A reusable workflow can be called by another workflow if one of the following is true:

• Both workflows are in the same repository.
• The reusable workflow is stored in a public repository, and your organization allows using public reusable workflows.
• The workflow is stored in a private repository, and the repository settings allow access to reusable workflows.

Access Requirements

To enable the reuse of workflows, you need to configure the Actions permissions for both private and public repositories. For private repositories, specific access policies must be set to allow external workflows to call the reusable ones.

Runners and Reusable Workflows

When using GitHub-hosted runners, the billing and execution context are always linked to the caller workflow. The reusable workflow will not use the runners from its own repository. All execution happens in the caller’s context, which affects billing.

However, when using self-hosted runners, the reusable workflow can access runners from the caller repository or the organization, as long as those runners are configured for the caller.

Creating a Reusable Workflow

Reusable workflows are YAML files, similar to standard workflow files, stored in the .github/workflows directory of a repository. To make a workflow reusable, it must include the workflow_call event trigger.

Example of a Reusable Workflow

Here is an example of a reusable workflow:

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}        

This workflow defines inputs (config-path) and secrets (token) that will be passed from the caller workflow and used in the reusable workflow.

Calling a Reusable Workflow

To call a reusable workflow, you use the uses keyword directly within a job definition, just like when you use actions. The syntax looks like this:

jobs:
  call-workflow:
    uses: organization/repository/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}
        

In this example, the workflow calls a reusable workflow located in another repository, passing parameters like config-path and token to the reusable workflow.

Using a Matrix Strategy with Reusable Workflows

You can also call reusable workflows within jobs that use the matrix strategy, which allows you to run multiple variations of a job by combining different variables. Here’s an example:

jobs:
  ReuseableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}
        

This job will run three times, once for each value (dev, stage, prod) in the target matrix, reusing the same deployment workflow.

Limitations of Reusable Workflows

There are a few limitations when using reusable workflows:

• You can nest up to four levels of reusable workflows.
• You can call a maximum of 20 unique reusable workflows from a single workflow file.
• Environment variables defined at the workflow level of the caller workflow are not propagated to the reusable workflow.
• You cannot use GITHUB_ENV to pass values between job steps in the caller workflow.

Conclusion

Reusing workflows in GitHub Actions brings numerous benefits, including reduced code duplication, consistent automation processes across projects, and easier maintenance of CI/CD pipelines. By centralizing reusable workflows in a library, organizations can create efficient, scalable automation systems that save time and promote best practices.

If you haven’t yet explored reusable workflows, now is the perfect time to leverage this powerful feature and streamline your automation processes in GitHub Actions!