Understanding and Using GitHub Reusable Workflows

GitHub Reusable Workflows are a feature of GitHub Actions that let you define a workflow once and reference it from multiple repositories, ensuring consistency, maintainability, and reusability across projects.

To use them, create a dedicated repository (or a folder in an existing one) with a .github/workflows directory, add a YAML file that defines the workflow, optionally declare inputs for parameterization, commit the file, and then reference it from other repositories via the uses keyword.

Below is a simple reusable workflow ( build.yml ) that accepts a target input and runs a matrix job for dev , stage , and prod environments:

name: Build

on:
  workflow_call:
    inputs:
      target:
        required: true
        type: string
        default: ""

jobs:
  build:
    strategy:
      matrix:
        target: [dev, stage, prod]
    runs-on: ubuntu-latest
    steps:
      - name: inputs.target = ${{ inputs.target }}
        if: inputs.target
        run: echo "inputs.target = ${{ inputs.target }}."
      - name: matrix.target = ${{ matrix.target }}
        if: matrix.target
        run: echo "matrix.target = ${{ matrix.target }}."

In another repository, you can call this workflow by creating a .github/workflows/build.yml file that points to the reusable workflow:

name: Build

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  call-build:
    uses: shenxianpeng/reuse-workflows-demo/.github/workflows/build.yml@main
    with:
      target: stage

GitHub recommends seven best practices for reusable workflows: modular design, parameterized configuration, version control, clear documentation and comments, security handling of secrets, thorough testing and validation, and performance optimization.

When compared with Jenkins Shared Libraries, both provide reusable automation components and support parameterization, but they differ in platform (GitHub Actions vs. Jenkins), syntax (YAML vs. Groovy), and ease of use—GitHub workflows are generally simpler for projects already hosted on GitHub, while Jenkins requires a dedicated server and plugin configuration.