Skip to main content

Pipelines

The Cloudbear Automation Platform (CAP) can automatically generate a dynamic GitLab CI/CD pipeline based on your config.cap.yaml. This allows you to build, test, and deploy your application with minimal CI/CD configuration.

Enabling the pipeline

To use the CAP-generated pipeline, you must include it in your project's .gitlab-ci.yml file. CAP provides a unique, stable URL for each application's pipeline configuration.

In your project's .gitlab-ci.yml file, add the following include directive at the top:

include:
  - remote: https://platform.cloudbear.it/api/v1/applications/<app_id>/pipelines/gitlab.yaml

Replace <app_id> with your application's unique ID.

Alternatively, some projects can be configured in the Cloudbear platform to use the CAP pipeline by default, without needing to modify the .gitlab-ci.yml.

Options

You can customize the behavior of the generated pipeline using the top-level pipeline key in your config.cap.yaml.

pipeline:
  context: apps/my-frontend
  suffix: frontend
  unifiedImage: true
  semanticRelease: true
Property Type Description Default
enable boolean Whether to generate any pipeline jobs at all. See Disabling jobs. true
suffix string A suffix added to every generated job name, such as build:cap. Useful when the CAP jobs run alongside your own. None
context string The subdirectory the pipeline runs from. Useful for monorepos. None
unifiedImage boolean Whether one image is built and promoted through every environment. See Image Strategies. true
semanticRelease boolean Whether to add semantic release jobs, which derive the version and changelog from your commit messages. false
onTag boolean or string Whether the environment deploys on a tag. A string is a regex and must include the / delimiters, as in /^v[0-9]+/. true for production and acceptance, false otherwise
onBranch string Deploys only on commits to this branch. Wrap it in / delimiters to match a regex instead of an exact name. None
defaultBranch boolean Whether the environment deploys on every commit to the project's default branch. true for staging when onTag is off, false otherwise
mergeRequest boolean Whether a plan job runs for merge requests targeting the onBranch branch. No deploy happens. true
build.enable boolean Whether the image is built. See Disabling jobs. true
build.size string The runner the build job runs on. One of small, medium or large. See Build size. small
release.enable boolean Whether the built image is tagged for the environment. Turning the build off turns this off too. true
plan.enable boolean Whether a plan job shows the changes a deploy would make. true
deploy.enable boolean Whether the environment is deployed. Turning the plan off turns this off too. true

The trigger properties (onTag, onBranch, defaultBranch, mergeRequest) decide when an environment deploys and belong in that environment's pipeline block. See Default triggers for what you get without setting any of them.

Build size

The build job runs on a small runner. Give it a bigger one when the build is slow or runs out of memory.

pipeline:
  build:
    size: medium

Any other value is ignored and the build runs on a small runner. A bigger runner can take longer to become available, so raise the size only for a build that needs it.

When each environment builds its own image (unifiedImage: false), setting size inside an environment's pipeline block changes only that environment's build job.

size applies to the build job and nothing else. The plan, deploy and release jobs always run on a small runner, whatever you set here. None of them compiles anything: the first two hand the work to CAP and wait for the result, and the release job copies an image between two tags in the registry. A bigger runner would do nothing for them but make them slower to start.

Configuration hierarchy

Pipeline settings can be defined at two levels in your config.cap.yaml:

  1. Top-Level: Global settings that apply to all pipeline jobs.
  2. Environment-Level: Settings defined within an environments block. These are merged with the top-level settings and are specific to that environment.

Instances are not supported for pipelines. The GitLab CI/CD system does not have the concept of CAP "instances". Therefore, pipeline configuration blocks cannot be defined inside an instances block. All pipeline settings must be at the top level or within a top-level environments block.

Disabling jobs

By default, all CAP pipeline jobs (build, release, plan, etc.) are enabled. You can selectively disable parts of the generated pipeline by setting the enable flag to false. This is useful if you only want to use CAP for certain tasks, like deployments, while handling builds in a separate pipeline.

pipeline:
  enable: false      # Disables ALL CAP pipeline jobs
  build:
    enable: false    # Disables only the 'build' jobs
  release:
    enable: false    # Disables only the 'release' jobs
  plan:
    enable: false    # Disables only the 'plan' jobs
  deploy:
    enable: false    # Disables only the 'deploy' jobs

Two of these follow from another: turning build off also turns release off, and turning plan off also turns deploy off.

Default triggers

Three environment slugs are recognized by name and get a deploy trigger without any pipeline configuration. Every other slug gets none:

Environment slug Deploys on Promotion
production Any tag Manual
acceptance Any tag Automatic
staging Every commit to the project's default branch Automatic
any other slug Set onBranch or onTag to choose Automatic

A manual promotion means the deploy job is created but waits: the pipeline stops at it and someone has to start it from GitLab. Every other environment deploys as soon as its trigger matches.

An environment named develop falls in the last row. To deploy it on every commit to a develop branch, set the branch explicitly:

environments:
  develop:
    pipeline:
      onBranch: develop

Deployment rules

You can control when deployments to a specific environment should occur by setting onTag, onBranch, defaultBranch and mergeRequest within that environment's pipeline block. These override the defaults above.

Setting onBranch turns onTag off unless you set onTag as well, so giving production or acceptance a branch replaces its tag trigger rather than adding to it. A production deploy always waits for a manual start, whichever trigger it runs on.

Examples

Deploy to Staging on develop branch, plan for MRs:

environments:
  staging:
    pipeline:
      onBranch: develop
      mergeRequest: true

Deploy to Production on version tags only (e.g., v1.2.3):

environments:
  production:
    pipeline:
      onTag: '/^v[0-9]+\.[0-9]+\.[0-9]+$/'

Deployment tiers

CAP automatically sets the deployment_tier on every deploy job based on the environment slug. This allows GitLab to track deployments in the correct tier for dashboards and notifications.

Environment slug GitLab deployment tier
production production
acceptance staging
staging testing
develop development
any other slug other

No configuration is required: the tier is derived automatically from the environment slug.

Back to top