# GitLab

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 collections 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

```yaml
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.

```yaml
include:
  - component: $CI_SERVER_FQDN/bluebricks-dev/workflow/bluebricks@1.0.0
    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/bluebricks@1.0.0
    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 collections 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`        | Collection 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**:

```yaml
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:

```yaml
inputs:
  config_file: $BLUEBRICKS_CONFIG
```

If not specified, it defaults to:

```
$HOME/.bricks/config.yaml
```

***

### Advanced Usage

#### Using Custom Flags

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

#### Using Variables in Inputs

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