GitHub Actions: workflow_run vs. workflow_call

GitHub Actions offers automation capabilities directly within the GitHub platform, allowing developers to automate software workflows. With a myriad of events and triggers available (as explored in my previous post, ‘GitHub Actions Workflow Triggers: A Comprehensive Categorization’), it’s sometimes challenging to discern the specific use and advantage of each. In this article, we’re going to focus on two intriguing triggers: workflow_run and workflow_call. What are they, and when should you use each?

What is workflow_run?

workflow_run is an event in GitHub Actions that gets triggered when a workflow completes (either succeeds or fails). It allows one workflow to trigger another workflow based on the completion of the first.

Use Cases:

• Dependency on another workflow: If one workflow’s completion is a prerequisite for starting another, workflow_run is handy. Imagine a scenario where one workflow prepares some data or sets up an environment, and a subsequent workflow utilizes that data. For instance, you might have a workflow that builds your application, another workflow that deploys the built application.
• Separation of concerns: Keep workflows modular and focused on a single task. Then, chain them together using workflow_run.
• Security: Since the triggered workflow runs in the context of the base repository, it has access to secrets even if it’s initiated by a pull request from a fork.

Example:

• First Workflow:

# .github/workflows/first_workflow.yml
name: First Workflow

on: [push]

jobs: 
  build:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v2
  
    - name: Build
      run: echo "Building the project..."

• Second Workflow:

# .github/workflows/second_workflow.yml
name: Second Workflow

on:
  workflow_run:
    workflows: ["First Workflow"]
    types:
      - completed

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps: 
    - name: Deploy
      run: echo "Deploying the project..."

In this example, when the First Workflow completes, the Second Workflow will be triggered due to the workflow_run event.

What is workflow_call?

Introduced in late 2021, the workflow_call event enables one workflow to use another reusable “callable” workflow. This promotes the reusability of workflows across different repositories or within the same repository.

Use Cases:

• Reusable Workflows: If multiple workflows share a series of steps, they can be abstracted into a workflow_call. Instead of duplicating workflow code in multiple places, create one “callable” workflow and have other workflows invoke it. This is especially useful for standard setup or deployment tasks.
• Centralizing logic: By centralizing the logic in a callable workflow, you can ensure consistency across multiple projects or repositories.
• Inputs and Outputs: workflow_call allows for passing inputs and getting outputs, much like function calls in programming.

Example:

• Callable Workflow:

# .github/workflows/callable_workflow.yml
name: Callable Workflow

on: 
  workflow_call:
    inputs:
      name: 
        description: 'Name for greeting'
        required: true
        type: 'string'
    outputs:
      greetingMessage: 
        description: 'Generated greeting message'
        value: ${{ steps.greeting.outputs.message }}

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
    - id: greeting
      run: echo "::set-output name=message::Hello, ${{ inputs.name }}"

• Calling Workflow:

# .github/workflows/calling_workflow.yml
name: Calling Workflow

on: [push]

jobs:
  useCallable:
    uses: ./.github/workflows/callable_workflow.yml
    with:
      name: 'Jimin'

The workflow_call feature expected the path to be relative to the root of the repository, which means you’d need to specify the full path to the workflow file, including the .github/workflows directory.

In this setup Calling Workflow uses the Callable Workflow and passes an input to it. The Callable Workflow then processes this input and could return outputs if needed.

Key Differences

• Purpose:
  - workflow_run: Used to trigger one workflow after the completion of another.
  - workflow_call: Enables workflows to be reusable and callable by other workflows.
• Use Case:
  - workflow_run: Chaining workflows based on the completion of a prior workflow.
  - workflow_call: Reusing the same workflow logic in multiple places.
• Context:
  - workflow_run: Runs in the context of the base repository, allowing it to access secrets even from forked pull requests.
  - workflow_call: Designed for reusability across repos or within the same repo.
• Inputs & Outputs:
  - While both can have inputs and outputs, workflow_call is designed for more interactive usage where you might pass data between the caller and callee workflows.

Conclusion

Both workflow_run and workflow_call serve essential roles in optimizing and modularizing workflows in GitHub Actions. workflow_run is about sequencing workflows based ont he completion status of another, while workflow_call focuses on reusability and centralizing workflow logic. Depending on the specific needs of your automation, you might find one more suitable than the other. However, in a well-structured CI/CD process, it’s not unusual to see both in action.