GitLab

Overview

The Bluebricks GitLab integration provides a workflow component for running Bluebricks CLI commands directly inside GitLab CI/CD pipelines. This enables teams to automate infrastructure deployments, update packages and blueprints, and manage IaC workflows in a repeatable, Git-driven pipeline.

By embedding Bluebricks operations inside your GitLab pipelines, you can enforce consistent deployment patterns, review infrastructure changes through merge requests, and integrate Bluebricks environments seamlessly into your CI/CD strategy.

---

Running Bluebricks in GitLab Pipelines

The Bluebricks GitLab Workflow Component allows you to execute CLI commands such as:

• Installing or updating deployments

• Generating plans before applying changes

• Publishing package and blueprint updates

• Running version bumps or validation commands

To use the component, include it in your .gitlab-ci.yml definition.

Basic Usage

include:
  - component: $CI_SERVER_FQDN/bluebricks-dev/workflow/bluebricks@VERSION
    inputs:
      stage: plan
      command: install
      plan_only: true
      file: deployment/infrastructure/bricks.yaml
      api_key: $BLUEBRICKS_API_KEY
      config_file: $BLUEBRICKS_CONFIG

Replace VERSION with the specific component version you want to use.

---

Example: Plan and Apply Workflow

This example defines a two-stage pipeline that first generates a plan and then applies the changes.

include:
  - component: $CI_SERVER_FQDN/bluebricks-dev/workflow/[email protected]
    inputs:
      stage: plan
      command: install
      plan_only: true
      file: deployment/aws-resources/bricks.yaml
      api_key: $BLUEBRICKS_API_KEY
      config_file: $BLUEBRICKS_CONFIG

  - component: $CI_SERVER_FQDN/bluebricks-dev/workflow/[email protected]
    inputs:
      stage: apply
      command: install
      plan_only: false
      file: deployment/aws-resources/bricks.yaml
      api_key: $BLUEBRICKS_API_KEY
      config_file: $BLUEBRICKS_CONFIG

stages:
  - plan
  - apply

This pattern mirrors classic IaC workflows, giving you a declarative way to manage environments with reviewable changes.

---

Configuration Inputs

The component supports a range of inputs depending on the command you run.

Required Inputs

Input	Description
stage	GitLab CI stage where the job executes
command	Primary Bluebricks CLI command (install, updateci, bprint, etc.)

Common Inputs

Input	Description	Default
cli_version	Bluebricks CLI version	1.58.0
api_key	API key for authentication	''
api_url	Bluebricks API endpoint	https://api.bluebricks.co
config_file	Path to CLI config file	$HOME/.bricks/config.yaml
flags	Extra CLI flags	''

---

Command-Specific Inputs

Install Command

Use these inputs when executing bricks install:

Input	Description	Default
file	Path to the bricks manifest YAML	''
package	Package name, if required	''
env	Environment slug	''
plan_only	Whether to generate a plan only	false
set_slug	Deployment slug	''
props	JSON string of properties	''
props_file	Path to properties JSON file	''

updateci Command

Input	Description	Default
artifacts_folder	Path to packages folder	bluebricks/packages
blueprints_folder	Path to blueprints folder	bluebricks/blueprints
artifact_bump	Package version bump type	patch
blueprint_bump	Blueprint version bump type	patch
output	Output format (ascii or json)	ascii
base	Base branch for diff	origin/main
head	Head ref for comparison	HEAD

bprint / bp Commands

Input	Description	Default
subcommand	e.g., publish, bump, validate	''
src	Blueprint source path	.
bump_type	Version bump type	''
version	Version spec	''

---

Authentication

To authenticate, store your Bluebricks API key as a protected GitLab CI/CD variable:

variables:
  BLUEBRICKS_API_KEY: $YOUR_PROTECTED_API_KEY

Refer to this variable in your component inputs.

---

Configuration File

The component can use a custom config file with:

inputs:
  config_file: $BLUEBRICKS_CONFIG

If not specified, it defaults to:

$HOME/.bricks/config.yaml

---

Advanced Usage

Using Custom Flags

inputs:
  command: install
  file: deployment/infrastructure.yaml
  flags: --dry --debug

Using Variables in Inputs

inputs:
  stage: deploy
  command: install
  file: deployment/$CI_ENVIRONMENT_NAME/bricks.yaml
  env: $CI_ENVIRONMENT_NAME