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 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 implements, reviews and rebases merge requests, and 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)

When pipelines run

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 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, build, test, and read-only diff jobs do.

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.

Usage

Add an include block to your .gitlab-ci.yml:

include:
  - project: hosstio/gitlab-pipelines
    file: pipelines/docker.yaml

Multiple pipelines can be combined:

include:
  - project: hosstio/gitlab-pipelines
    file: pipelines/docker.yaml
  - project: hosstio/gitlab-pipelines
    file: pipelines/kubernetes-helm.yaml

Recommended setup

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.

1. Create a pipelines project in your GitLab group (e.g. myorg/pipelines).

2. Add an application.yaml that includes the pipelines you need and sets shared variables:

   # 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
   precommit:
     allow_failure: true
   yamllint:
     allow_failure: true
   hadolint:
     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-cluster

3. In each application repository, include only your pipeline project:

   # .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