Reusable Workflows

Reusable workflows allow you to define a set of jobs and steps once and invoke them from multiple workflows, improving maintainability, consistency, and efficiency.

Defining a Reusable Workflow

A reusable workflow is invoked from a caller job. The syntax for defining a caller job is as follows:

metadata:
  name: Main
jobs:
  caller-job:
    uses: {repository}#{repository_name/path/to/workflow.yaml}@{branch|tag|commit}
    with: # Optional: Define input parameters
      input1: 'foo'
      input2: 'bar' 

The uses field is mandatory and specifies the reusable workflow to be called. It includes the Git repository URL where the workflow file resides, the full path to the workflow file within the repository, and, optionally, the branch name, tag, or commit hash to check out.

The with section is optional and allows passing input parameters to the called workflow. These inputs must match the inputs defined in the reusable workflow, otherwise, the job will fail.

Warning

If the called workflow defines channel (or job) hooks, they will not be executed. This feature is planned for implementation in an upcoming release.

Passing Inputs and Outputs

When a caller job is launched, it downloads and executes the called workflow, passing input parameters and retrieving outputs generated by the called workflow when needed.

In the following example, the main workflow passes the input_1 value to the called workflow and retrieves its output using needs (on the job level) or jobs (on the workflow level) context.

Both workflows contain regular jobs that echo "hello world", demonstrating the use of inputs and outputs. Additionally, the called workflow’s output is made available as an output of the main workflow.

metadata:
  name: Main
jobs:
  caller-job:
    uses: http://git.server/my_awesome_repo.git#my_awesome_repo/wf/workflow.yaml
    with:
      input_1: 'hello'
  regular-job:
    needs: ['caller-job']
    steps:
      - run: echo "hello ${{ needs.caller-job.outputs.called-workflow-output }}"
outputs:
  called-workflow-output:
    value: ${{ jobs.caller-job.outputs.called_workflow_output }}

metadata:
  name: Called
inputs:
  input_1:
    description: 'Called workflow input'
    required: false
    default: ''
jobs:
  regular-job:
    outputs:
      output_1: ${{ steps.output_step.outputs.output_1 }}
    steps:
      - run: echo "${{ inputs.input_1 }} world"
      - id: output_step
        run: echo "::set-output:: name=output_1::world"
outputs:
  called_workflow_output:
    value: ${{ jobs.regular-job.outputs.output_1 }}

Setting Download Environment Tags

The caller job creates a sub-job that checks out the git repository and downloads the workflow file from the path specified. The download job execution environment or runs-on tags use can be configured via the arranger service configuration options download_job_tags and download_job_parents_tags.

The download_job_tags parameter is a comma-separated string of values or tags that define the environment used to download the called workflow.

The download_job_parents_tags parameter can be set to use or ignore, determining whether the caller job runs-on tags should be inherited or ignored by the download job.

In the following example, assuming the download_job_tags value is foo,bar and the download_job_parents_tags value is use, the called workflow file will be downloaded using an environment defined by the tags linux,foo,bar:

metadata:
  name: Main
jobs:
  caller-job:
    runs-on: ['linux']
    uses: http://git.server/my_awesome_repo.git#my_awesome_repo/wf/workflow.yaml