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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/integrations/gitlab.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.