I recently started a new role where all of our repositories are hosted on GitHub. For the past five years I worked exclusively with GitLab, where we maintained a central pipelines repository and included shared GitLab CI configuration from each project to avoid duplicating pipeline logic. Is there an equivalent pattern in GitHub Actions, and how does it compare to GitLab's includes?
4 Answers
GitHub Actions does not have a direct equivalent to GitLab's YAML `include` that simply splices configuration into the caller. Reusable workflows are the better fit when the shared code owns jobs, runners, or multiple stages. Composite actions are better for small, atomic pieces such as setting up a tool, applying tagging conventions, or publishing an artifact. Keeping those pieces composable usually makes the calling workflow easier to understand than creating one huge company-wide template action.
Yes, a central repository works well for this. You may want to separate workflows by sensitivity: shared workflows that need permissions such as `contents: write` should be isolated or tightly controlled. Also review the permissions granted to the caller, pin shared workflows to reviewed tags or commit SHAs, and avoid giving every consuming repository more access than it needs.
The closest equivalent is a reusable workflow. Put a workflow in a central repository under `.github/workflows/` and give it the `workflow_call` trigger. Individual repositories can then invoke it with something like `uses: your-org/pipeline-templates/.github/workflows/build.yml@v1`, passing configuration through inputs. Referencing a tag or commit is generally safer than relying on `main`.
For shared steps inside a single job, use a composite action instead. A useful rule of thumb is reusable workflows for complete jobs or pipelines, and composite actions for a reusable group of steps.
A few GitHub-specific details can cause surprises during migration. Inputs should be used for most configuration because environment variables do not pass between the caller and reusable workflow in the same way they do with GitLab includes. Values produced by one job may need to be exposed as outputs and consumed through `needs`. Secrets also are not automatically available; the caller may need to specify `secrets: inherit`, or explicitly map the secrets the workflow is allowed to use.
Another option when environment handling is the main problem is a composite action, since it runs within the caller's job context. It still cannot replace a reusable workflow when you need multiple jobs.
Reusable workflows also have nesting and composition limitations, so trying to reproduce a deeply layered GitLab include hierarchy can become difficult. Keeping the shared pieces relatively small helps with readability and security.