The Ultimate Guide to GitHub Reusable Workflows: Maximize Efficiency and Collaboration

GitHub reusable workflows, a feature of GitHub Actions, are a powerful tool for CI/CD (continuous integration and continuous deployment). They allow you to create workflows that can be used across multiple repositories, reducing the need for copying and pasting code and promoting best practices.

Reusable workflows are stored in workflow files within the .github/workflows directory of a repository. They can be called by a caller workflow in the same repository, a different repository, or even a private repository. This flexibility makes reusable workflows a central part of building efficient GitHub Actions.

The concept of workflow reuse is built on the idea of avoiding duplication. By reusing workflows, you can maintain a single source of truth for your CI/CD processes. This is especially useful for large projects where multiple workflows might be doing similar tasks.

1     // Example of a reusable workflow file
2    name: Reusable Workflow
3    on: [push, pull_request]
4    jobs:
5      build:
6        runs-on: ubuntu-latest
7        steps:
8        - uses: actions/checkout@v2
9        - name: Set up Node.js
10          uses: actions/setup-node@v2
11          with:
12            node-version: 14
13        - name: Install dependencies
14          run: npm ci
15        - name: Run tests
16          run: npm test
17     

The Process of Reusing a GitHub Workflow Action

To reuse a GitHub workflow action, you need to create a caller workflow file that references the reusable workflow. The caller workflow file is also stored in the .github/workflows directory of your repository.

When creating the caller workflow file, you need to specify the repository where the reusable workflow is stored (if it's not in the same repository), the ref (branch, tag, or SHA), and the path to the workflow file. You can also pass data to the reusable workflow using inputs.

1     // Example of a caller workflow file
2    name: Caller Workflow
3    on: [push, pull_request]
4    jobs:
5      build:
6        uses: my-org/my-repo/.github/workflows/reusable-workflow.yml@main
7        with:
8          input1: value1
9          input2: value2
10     

In the above example, the caller workflow triggers the reusable workflow stored in the my-org/my-repo repository on the main branch. It also passes two inputs (input1 and input2) to the reusable workflow.

Composite Action vs Reusable Workflows: A Comparative Analysis

Both composite actions and reusable workflows are features of GitHub Actions that allow you to reuse code. However, they serve different purposes and have different capabilities.

Composite actions allow you to combine multiple steps into a single action. They are defined in a single file and can include runs of shell commands and uses of other actions. Composite actions are useful when you want to reuse a sequence of steps across multiple jobs or workflows.

On the other hand, reusable workflows allow you to reuse an entire workflow, including all its jobs and steps. They are more powerful than composite actions as they can include environment variables, secrets, and even other workflows. Reusable workflows are ideal when you want to reuse a complete CI/CD process across multiple repositories.

1     // Example of a composite action
2    name: 'Composite Action'
3    description: 'A composite action that runs a sequence of steps'
4    runs:
5      using: 'composite'
6      steps:
7        - run: echo "Step 1"
8          shell: bash
9        - run: echo "Step 2"
10          shell: bash
11     

In the above example, the composite action combines two steps (echo "Step 1" and echo "Step 2") into a single action. This composite action can be used in any job or workflow that requires these two steps.

The Role of Composite Actions and Reusable Workflows in GitHub Actions

GitHub Actions is a powerful tool that allows you to automate software workflows directly in your GitHub repository. It provides several features to create, customize, and manage workflows, including composite actions and reusable workflows.

Composite actions, as mentioned earlier, allow you to combine multiple steps into a single action. This is useful when you have a sequence of steps that you use frequently in your workflows. By creating a composite action, you can reuse this sequence of steps with just a single line in your workflow file.

On the other hand, reusable workflows allow you to reuse an entire workflow, including all its jobs and steps. This is useful when you have a complete CI/CD process that you want to use across multiple repositories. By creating a reusable workflow, you can maintain a single source of truth for your CI/CD process and promote best practices across your organization.

Both composite actions and reusable workflows play a crucial role in building efficient and maintainable GitHub Actions. They help reduce duplication, promote reuse, and make your workflows easier to understand and manage.

1     // Example of using a composite action in a workflow
2    name: Main Workflow
3    on: [push, pull_request]
4    jobs:
5      build:
6        runs-on: ubuntu-latest
7        steps:
8        - uses: actions/checkout@v2
9        - name: Run composite action
10          uses: my-org/my-repo/.github/actions/my-composite-action@main
11     

In the above example, the main workflow uses a composite action (my-composite-action) stored in the my-org/my-repo repository. This composite action is used as a step in the build job of the main workflow.

The Possibility of Multiple Workflows in GitHub Actions

GitHub Actions allows you to have multiple workflows in a single repository. Each workflow is defined in a separate YAML workflow file in the .github/workflows directory of your repository.

Having multiple workflows can be useful in several scenarios. For example, you might want to have separate workflows for different events (like push and pull requests), different branches, or different types of tasks (like building, testing, and deploying your code).

You can also use multiple workflows to organize your CI/CD processes in a modular way. For example, you can create a reusable workflow for a common task (like running tests) and call this reusable workflow from other workflows in your repository.

1     // Example of multiple workflows in a repository
2    // .github/workflows/build.yml
3    name: Build
4    on: [push]
5    jobs:
6      build:
7        runs-on: ubuntu-latest
8        steps:
9        - uses: actions/checkout@v2
10        - name: Build code
11          run: npm run build
12    
13    // .github/workflows/test.yml
14    name: Test
15    on: [push]
16    jobs:
17      test:
18        uses: my-org/my-repo/.github/workflows/run-tests.yml@main
19     

In the above example, there are two workflows (build and test) in the repository. The build workflow is responsible for building the code, while the test workflow calls a reusable workflow (run-tests) to run the tests. This setup allows for a modular and organized CI/CD process.

Distinguishing Between Reusable Workflow and Custom Action

While both reusable workflows and custom actions allow you to reuse code in GitHub Actions, there are some key differences between them.

A reusable workflow is a complete workflow that can be reused across multiple repositories. It includes all the jobs and steps of the workflow, and can include environment variables, secrets, and even other workflows. A reusable workflow is defined in a YAML workflow file and can be called from another workflow using the uses keyword.

On the other hand, a custom action is a self-contained piece of code that can be used as a step in a job. It can be written in any language that can run on GitHub's runners (like JavaScript, Python, or Shell), and it can include inputs and outputs to pass data to and from the action. A custom action is defined in a Dockerfile or JavaScript file and can be used in a workflow using the uses keyword.

In general, you would use a reusable workflow when you want to reuse a complete CI/CD process, and a custom action when you want to reuse a specific task or sequence of steps.

1     // Example of a custom action
2    // action.yml
3    name: 'Custom Action'
4    description: 'A custom action that prints a message'
5    inputs: message:
6    description: 'The message to print'
7    required: true
8    runs:
9    	using: 'node12'
10    	main: 'index.js'
11    
12    // index.js
13    const core = require('@actions/core');
14    const message = core.getInput('message');
15    console.log(message);
16     

In the above example, a custom action is created that takes an input (message) and prints it. This custom action can be used as a step in any job in a workflow.

Triggering GitHub Actions Workflow from Another Workflow: A How-To Guide

In GitHub Actions, you can trigger one workflow from another using the workflow_run event. This allows you to create complex CI/CD processes that involve multiple workflows.

To trigger a workflow from another workflow, you need to specify the workflow_run event in the on section of your workflow file. You also need to specify the workflow field to indicate the name of the workflow that should trigger this workflow.

1     // Example of triggering a workflow from another workflow
2    // .github/workflows/triggered-workflow.yml
3    name: Triggered Workflow
4    on:
5      workflow_run:
6        workflows: ["Main Workflow"]
7        types:
8          - completed
9    jobs:
10      build:
11        runs-on: ubuntu-latest
12        steps:
13        - uses: actions/checkout@v2
14        - name: Build code
15          run: npm run build
16     

In the above example, the Triggered Workflow will be triggered whenever the Main Workflow is completed. This setup allows you to create a sequence of workflows that run one after another.

The Art of Reusing a Workflow in GitHub

Reusing a workflow in GitHub involves creating a reusable workflow and then calling it from another workflow. The reusable workflow is a complete workflow that is stored in a YAML workflow file in the .github/workflows directory of your repository. The caller workflow is another workflow that uses the uses keyword to call the reusable workflow.

When creating a reusable workflow, you can include any jobs and steps that you would include in a regular workflow. You can also include environment variables and secrets, and you can use the inputs and outputs keywords to pass data to and from the workflow.

When calling a reusable workflow, you need to specify the repository where the workflow is stored (if it's not in the same repository), the ref (branch, tag, or SHA), and the path to the workflow file. You can also pass inputs to the workflow using the with keyword.

1     // Example of reusing a workflow in GitHub
2    // .github/workflows/reusable-workflow.yml
3    name: Reusable Workflow
4    on:
5      workflow_call:
6        inputs:
7          input1:
8            required: true
9            type: string
10        outputs:
11          output1:
12            type: string
13    jobs:
14      build:
15        runs-on: ubuntu-latest
16        steps:
17        - uses: actions/checkout@v2
18        - name: Build code
19          run: npm run build
20        - name: Set output
21          id: set_output
22          run: echo "::set-output name=output1::value1"
23    
24    // .github/workflows/caller-workflow.yml
25    name: Caller Workflow
26    on: [push, pull_request]
27    jobs:
28      build:
29        uses: my-org/my-repo/.github/workflows/reusable-workflow.yml@main
30        with:
31          input1: value1
32     

In the above example, the Caller Workflow calls the Reusable Workflow and passes an input (input1) to it. The Reusable Workflow uses this input in its build job and sets an output (output1) that can be used by the Caller Workflow.

Running One Workflow After Another in GitHub: A Step-by-Step Guide

In GitHub Actions, you can run one workflow after another by using the workflow_run event. This event is triggered whenever a workflow run is requested or completed, allowing you to create a sequence of workflows that run in a specific order.

Here's a step-by-step guide on how to set this up:

1. Create the first workflow (let's call it Workflow A). This workflow can be triggered by any event (like push, pull_request, etc.) and can include any jobs and steps that you need.

1     // .github/workflows/workflow-a.yml
2    name: Workflow A
3    on: [push]
4    jobs:
5      build:
6        runs-on: ubuntu-latest
7        steps:
8        - uses: actions/checkout@v2
9        - name: Build code
10          run: npm run build
11     

1. Create the second workflow (let's call it Workflow B). In the on section of this workflow file, specify the workflow_run event and the name of Workflow A.

1     // .github/workflows/workflow-b.yml
2    name: Workflow B
3    on:
4      workflow_run:
5        workflows: ["Workflow A"]
6        types:
7          - completed
8    jobs:
9      test:
10        runs-on: ubuntu-latest
11        steps:
12        - uses: actions/checkout@v2
13        - name: Run tests
14          run: npm test
15     

In the above example, Workflow B will be triggered whenever Workflow A is completed. This setup allows you to create a sequence of workflows that run one after another.

Rerunning a Failed Workflow in GitHub: Best Practices and Tips

In GitHub Actions, if a workflow fails, you can rerun it directly from the Actions tab in your repository. However, there are some best practices and tips that you should follow to handle failed workflows effectively:

1. Use clear and descriptive names for your workflows and jobs: This makes it easier to identify which workflow or job has failed and needs to be rerun.
2. Include error handling in your workflows: This can help prevent failures in the first place. For example, you can use the continue-on-error keyword to allow a job to continue even if a step fails.
3. Monitor your workflows: GitHub provides several features to help you monitor your workflows, like notifications, logs, and the Actions tab in your repository. Use these features to keep an eye on your workflows and quickly identify any failures.
4. Use the workflow_run event to automatically rerun failed workflows: You can create a workflow that is triggered by the workflow_run event and the failure type. This workflow can then use the GitHub API to rerun the failed workflow.

1// .github/workflows/rerun-failed-workflow.yml
2name: Rerun Failed Workflow
3on:
4  workflow_run:
5    workflows: ["Main Workflow"]
6    types:
7      - failure
8jobs:
9  rerun:
10    runs-on: ubuntu-latest
11    steps:
12    - name: Rerun failed workflow
13      run: |
14        curl -X POST \
15          -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
16          -H "Accept: application/vnd.github.v3+json" \
17          https://api.github.com/repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/rerun
18
19     

In the above example, the Rerun Failed Workflow is triggered whenever the Main Workflow fails. It then uses the GitHub API to rerun the failed workflow. This setup allows you to automatically rerun failed workflows and improve the reliability of your CI/CD processes.

Short on time? Speed things up with DhiWise!

Tired of manually designing screens, coding on weekends, and technical debt? Let DhiWise handle it for you!

You can build an e-commerce store, healthcare app, portfolio, blogging website, social media or admin panel right away. Use our library of 40+ pre-built free templates to create your first application using DhiWise.