GitHub Reusable Workflows vs. Composite Actions

Everyone knows GitHub as a platform for storing private and public Git repositories and collaborating with other developers. But besides storing repositories, GitHub also offers features like Issues, Project boards, Wiki’s and GitHub Actions. These last ones can be used to automate your workflows. In this article we will focus on a special kind of workflow and actions: Reusable Workflows and Composite Actions.

You can use workflows to build, test and release your code and much more. A workflow can be triggered by an extensive list of events and will run on GitHub hosted runners, for example Windows, Linux or Mac machines. It is also possible to setup your own runners on-prem. A GitHub workflow consists of Actions. These actions are building blocks of your workflow. Some examples of such actions are Checkout, Setup Java JDK, Upload a Build Artifact, etc. You can use existing Actions from the Marketplace or create your own JavaScript, TypeScript or Docker Action.

 

Reusable Workflows

As the name suggests, you can reuse a Reusable Workflow in one or more workflows. They are especially useful when you have multiple repositories in which you need to run the same workflows. When calling a reusable workflow, it is possible to provide a couple of input parameters and secrets. These can be used to provide some additional configuration to the reusable workflow, while the secrets might be used to publish the building artifacts. It is important to note that the secrets are always stored on the “calling” repository. This is the repository which is using the reusable workflow.

 

Example

For example, we have two repositories (A and B) which contain Java code. In both repositories we need a workflow to build and test our Java code. Instead of creating and maintaining the workflow in both repositories, we introduced a third repository (C). This contains a reusable workflow for building and testing Java code. In repository A and B, we create a very simple workflow which will call the central workflow. By doing this we have to maintain the build-workflow only at one place.

 

Composite Actions

Next to reusable workflows, GitHub also offers Composite Actions. These are a special type of GitHub actions which can be used to group “normal” actions. Just like a normal Action, a composite action can have some inputs and outputs. Unlike normal Actions it is not possible to write code inside a Composite Action, you can only call other Actions and write shell scripts. A Composite Action is mainly useful to keep your workflows clean and limit the number of Actions called in a workflow. This will improve the readability and maintainability of your workflows.

 

Example

The image below contains an example of a Composite Action. This action will generate a text file based on input data and store this file as an artifact in GitHub.

 

The action can now be used in a workflow where you should provide the filename and desired file content.

 

In the execution of this workflow you will see that the steps defined in the Composite Action are displayed as one step, called Create file.

 

Reusable Workflows vs. Composite Actions

Although both concepts sound very similar, there are some important differences. In brief you could say that Reusable Workflows define what should happen, while Composite Actions define how it should happen.

 

Reusable Workflow

Just like a normal workflow, a Reusable Workflow can contain multiple jobs. For each job you can define on which runner the jobs should be executed. When calling a Reusable Workflow, you can provide some inputs and secrets.

 

Composite Action

A Composite Action will always be used within a workflow, so it is not possible to define jobs or runners within the action. In a Composite Action you can define inputs, but it is not possible to define secrets explicitly. It is possible to call multiple Composite Actions inside your workflow, but you can only call one Reusable Workflow within a workflow. When you call a Reusable Workflow, you cannot add additional steps. It can only contain one step, which is the call to the Reusable Workflow.

 

Conclusion

Both Reusable Workflows and Composite Actions are very useful and powerful. They will keep your workflows clean and easier to maintain. Depending on your needs and situation you might prefer one over the other. But they can definitely be combined to get the most out of them.