GitHub Composite Actions: Script Your CI Steps

Why it exists

To solve the problem of duplication in workflow files. Instead of copy-pasting the same set of run commands across multiple jobs or workflows, you can define them once and reuse them, making your CI configuration cleaner and easier to maintain under the DRY (Don't Repeat Yourself) principle.

The mental model

Think of a composite action as a function or a shell script for your CI pipeline. You define a sequence of steps, give it a name, and then call that "function" from your main workflow. It encapsulates a multi-step process into a single, reusable action, abstracting away the implementation details.

How it works

You create an action.yml file, typically within the .github/actions directory of your repository. In this file, you specify runs: { using: 'composite' }. Underneath that, you define a steps key, which contains the sequence of shell commands or other actions you want to bundle. You can define inputs to pass parameters into your action and outputs to pass results back to the calling workflow.

When to use it

Use composite actions when you have a series of shell commands or simple actions that you find yourself repeating. It's ideal for tasks like setting up a specific environment, running a build process, executing a test suite, or performing a simple deployment script. They are best for logic that is self-contained within a single repository.

When not to use it

Avoid composite actions if you need complex conditional logic, require bundled dependencies, or need to support multiple operating systems with different shell syntax. For those cases, a JavaScript or Docker container action is more appropriate. The biggest footgun is that you cannot call a composite action from within another composite action; the nesting is not supported.

One canonical example

A common use case is creating a setup-and-test action for a project. The action.yml would define steps to check out the code, set up the required language version (e.g., Node.js), install dependencies (npm ci), and finally execute the tests (npm test). The main workflow then just calls this single action with uses: ./.github/actions/setup-and-test.