Set Up a GitLab CI/CD Pipeline

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.

Configuration Hierarchy for Pipelines

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

Top-Level: Global settings that apply to all pipeline jobs.
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.

Enabling the CAP 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/applications/<app_id>/pipeline#pipeline.yml'
```
Replace <app_id> with your application's unique ID.
The #pipeline.yml at the end of the URL is required by GitLab.

Note

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.

Top-Level Pipeline Configuration

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

Property	Type	Description
`suffix`	`string`	Adds a suffix to all generated job names (e.g., `build:cap`). Useful for running alongside existing pipelines.
`context`	`string`	Specifies a subdirectory to run the pipeline from. Useful for monorepos.
`unifiedImage`	`boolean`	Optimizes the pipeline for static front-end applications that use a "unified image". Defaults to `true`.
`semanticRelease`	`boolean`	Enables semantic release pipeline steps (e.g., automated versioning and changelog generation). Defaults to `false`.

Example

pipeline:
  context: "apps/my-frontend"
  suffix: "frontend"
  unifiedImage: true
  semanticRelease: true

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

Deployment Rules

You can control when deployments to a specific environment should occur by defining rules within that environment's pipeline block.

Property	Type	Description
`onTag`	`boolean`/`string`	If `true`, deploys only on Git tags. If a string (regex), deploys only on tags matching the pattern. Defaults to `true` for `production` and `acceptance` environments.
`onBranch`	`string`	If a string (regex), deploys only on commits to branches matching the pattern.
`defaultBranch`	`boolean`	If `true`, enables deployments on every commit to the project's default branch. Defaults to `true` for `staging` environments if `onTag` is not set.
`mergeRequest`	`boolean`	If `true`, runs a `plan` job (but does not deploy) for merge requests targeting the `onBranch` branch. Defaults to `true`.

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]+$/'