Pipelines
Pre-built pipelines you can import directly into your .gitlab-ci.yml.
Each pipeline defines its jobs, stages, and default variables. Override any variable to customise behaviour.
Available pipelines
| Pipeline | Description |
|---|---|
| Default | YAML and Markdown linting and pre-commit hooks for any project |
| Docker | Build and publish images with BuildKit and registry layer caching |
| Kubernetes | Deploy to Kubernetes with Helm, DigitalOcean, or Google Cloud |
| AI agents | Claude and Codex implement, review and rebase merge requests, and Claude posts scheduled status updates and audits to Slack |
| Node.js | Install, lint, test, build, and publish Node.js projects (planned) |
| Python | Install, lint, test, and publish Python projects (planned) |
| Terraform / OpenTofu | Manage infrastructure as code (planned) |
Pipeline types
Which pipeline type runs is decided by the workflow: rules, independently of which jobs run within it. A branch with an open merge request runs a merge request pipeline, and the same push does not also start a branch pipeline. The default branch is the exception: it always keeps its branch pipeline, so in gitflow develop keeps deploying while a develop → main merge request is open.
| Ref pushed | Open merge request? | Pipeline that runs |
|---|---|---|
| Feature branch (not the default branch) | Yes (it is the MR source) | Merge request pipeline |
| Feature branch | No | Branch pipeline |
Default branch (e.g. main or develop) | Either way | Branch pipeline (never a merge request pipeline) |
| Git tag | n/a | Tag pipeline |
| Pipeline schedule | n/a | Scheduled pipeline (no deploys) |
Scheduled pipelines
Scheduled pipelines set CI_COMMIT_BRANCH like a branch pipeline, so the deploy and apply jobs guard against them explicitly and never run on a schedule. Quality jobs skip them as well, since a schedule lints a commit that its push pipeline already linted. Build, test, and read-only diff jobs do run.
Auto-cancel
With the project's Auto-cancel redundant pipelines setting on, a newer push cancels the older pipelines on its branch, except on the default branch: the workflow sets auto_cancel:on_new_commit: none there, so every push to the default branch runs to the end, deploys included. A project with its own workflow: keeps a rule that does the same.
Preview environments
Preview environments are only deployed for feature branches: automatically in a merge request pipeline, manually on a branch pipeline with no open MR. The default branch and the long-lived develop, main, and master branches never get a preview.
Job rules
A job that checks files, such as yaml, markdown or dockerfile, runs on a branch only when the branch changed one of its files. A merge request pipeline compares the source branch with the target branch, and a branch pipeline without a merge request compares the branch with the default branch, so both see every change on the branch since it left the target or default branch. pre-commit checks all files, so it always runs. docker:image and the deploys don't check files, so they run on every commit to the default branch; README changes explains why and how to change that.
The default branch and git tags run every job whose files exist in the repository, and so does a branch pipeline started by hand or through the API, which has no push to compare with. Scheduled pipelines skip the jobs that check files, since the push pipeline already checked the commit.
Custom file lists
A job's rules: in your own .gitlab-ci.yml replaces the included ones, so copy the job's rules and change its file list in both places. For example, to lint only the Markdown under docs/:
markdown:
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
when: never
- if: $CI_COMMIT_TAG || $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || ($CI_COMMIT_BRANCH && $CI_PIPELINE_SOURCE != "push")
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
changes: &markdown_changes
- "docs/**/*.md"
- if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH
changes:
paths: *markdown_changes
compare_to: refs/heads/$CI_DEFAULT_BRANCHThe anchor (&markdown_changes) keeps the list in one place within your file. To run a job in every pipeline instead, set its rules to - when: on_success.
Usage
Add an include block to your .gitlab-ci.yml:
include:
- project: hosstio/gitlab-pipelines
file: pipelines/docker.yamlMultiple pipelines can be combined:
include:
- project: hosstio/gitlab-pipelines
file: pipelines/docker.yaml
- project: hosstio/gitlab-pipelines
file: pipelines/kubernetes-helm.yamlGroup pipeline project
Rather than referencing this project directly from every repository, create a dedicated pipeline project in your GitLab group and centralise configuration there. This gives you a single place to pin versions, set organisation-wide defaults, and roll out changes across all applications at once.
Create a
pipelinesproject in your GitLab group (e.g.myorg/pipelines).Add an
application.yamlthat includes the pipelines you need and sets shared variables:yaml# application.yaml in myorg/pipelines include: - project: hosstio/gitlab-pipelines file: pipelines/default.yaml - project: hosstio/gitlab-pipelines file: pipelines/docker.yaml - project: hosstio/gitlab-pipelines file: pipelines/kubernetes-helm.yaml variables: GOOGLE_PROJECT: myorg-staging GOOGLE_KUBERNETES_CLUSTER: myorg-cluster GOOGLE_REGION: europe-west4 KUBERNETES_CLUSTER: $GOOGLE_KUBERNETES_CLUSTER SLACK_MESSAGE_CHANNEL: deployments SLACK_MESSAGE_BRANDING: "by <https://gitlab.com/myorg/pipelines|myorg>" # Allow quality jobs to fail without blocking the pipeline pre-commit: allow_failure: true yaml: allow_failure: true dockerfile: allow_failure: true # Clear runner tags if you use custom runners instead of GitLab SaaS runners .docker_buildx: tags: [] # Use a separate cloud project and cluster for production production: variables: GOOGLE_PROJECT: myorg-production GOOGLE_KUBERNETES_CLUSTER: myorg-prod-clusterIn each application repository, include only your pipeline project:
yaml# .gitlab-ci.yml include: - project: myorg/pipelines file: application.yaml
Per-project overrides still work normally by setting variables in .gitlab-ci.yml:
include:
- project: myorg/pipelines
file: application.yaml
variables:
DOCKER_BUILD_TARGETS: deps build