# Bicep

## Overview

Bicep artifacts let you manage Azure infrastructure using native Bicep templates while taking advantage of Bluebricks' orchestration, collection management, and environment automation. You describe Azure resources declaratively using the Bicep language, then deploy and track environments consistently across all collections through Bluebricks.

<table><thead><tr><th width="219.7265625">Feature</th><th>Details</th></tr></thead><tbody><tr><td><strong>Azure-native IaC</strong></td><td>Full Bicep language support including modules, loops, conditions, and decorators</td></tr><tr><td><strong>What-if plan</strong></td><td>Plan runs <code>az deployment what-if</code> to preview changes without altering resources</td></tr><tr><td><strong>Deployment modes</strong></td><td>Complete (default) or Incremental mode for resource lifecycle control</td></tr><tr><td><strong>Parameter injection</strong></td><td>Props and secrets are passed as deployment parameters at runtime</td></tr><tr><td><strong>No state backend to manage</strong></td><td>Bluebricks tracks deployment metadata internally; no user-managed state backend required</td></tr></tbody></table>

For a complete guide to how inputs and outputs work across all IaC tools, see [Inputs & Outputs](/docs/orchestration/packages/inputs-and-outputs.md).

## Required files and directory structure

A Bicep artifact requires at least one `.bicep` file in the directory specified by `native.path`:

```
my-bicep-artifact/
├── bricks.json              # Artifact manifest
├── main.bicep               # Main Bicep template
└── modules/                 # Bicep modules (optional)
    ├── storage.bicep
    └── networking.bicep
```

The `native.path` field in `bricks.json` points to the directory containing your Bicep files.

{% hint style="warning" %}
The Bicep entry file **must** be named `main.bicep`. Bluebricks uses this file as the entry point for parameter extraction, output capture, and runtime execution. Module files in subdirectories can use any name.
{% endhint %}

## bricks.json reference

<table><thead><tr><th width="92.49609375">Field</th><th width="112.31640625">Required</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td>Yes</td><td><code>"bicep"</code></td></tr><tr><td><strong><code>path</code></strong></td><td>Yes</td><td>Directory containing the Bicep template files</td></tr><tr><td><strong><code>mode</code></strong></td><td>No</td><td>Deployment mode: <code>"Complete"</code> (default) or <code>"Incremental"</code>. See <a href="/pages/YyIxHkxz9xrh2xm2AamQ">Deployment Modes</a></td></tr></tbody></table>

### Example bricks.json

```json
{
  "name": "azure-storage",
  "version": "0.1.0",
  "description": "Azure storage account",
  "native": {
    "type": "bicep",
    "path": ".",
    "mode": "Complete"
  },
  "props": {
    "location": {
      "type": "string",
      "default": "East US",
      "description": "Azure region for resource group and resources"
    },
    "storageAccountName": {
      "type": "string",
      "description": "Storage account name"
    }
  },
  "outs": {
    "storageAccountId": {
      "type": "string",
      "description": "Storage account resource ID"
    }
  }
}
```

## How to create this artifact

The only requirement is a directory with valid Bicep files. If you can run `az deployment group create` from it, Bluebricks can use it as-is. Bluebricks handles parameter injection, deployment mode selection, and Azure authentication for you.

You can create a Bicep artifact in two ways:

* **In the Bluebricks app** during [blueprint creation](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md): select your repository and the directory containing your `.bicep` files, and Bluebricks generates the artifact automatically
* **Via CLI**: use the `bricks blueprint prepare` workflow described below

### Create a Bicep artifact via CLI

**Prerequisites:**

* Bluebricks CLI installed and authenticated (`bricks login`)
* Existing Bicep code (`.bicep` files)
* Azure account with appropriate permissions

**Steps:**

1. **Navigate to your Bicep directory:**

   ```bash
   cd ~/my-bicep-project
   ```
2. **Run blueprint prepare:**

   ```bash
   # Option 1: In-place (keeps original files)
   bricks blueprint prepare --source . --iac-type bicep

   # Option 2: With output directory (copies files to src/bicep/)
   bricks blueprint prepare --source . --output ./dist --iac-type bicep
   ```
3. **Publish the package:**

   ```bash
   bricks blueprint publish
   ```

**Example directory structure:**

Before:

```
my-bicep-project/
├── main.bicep
├── modules/
│   ├── storage.bicep
│   └── networking.bicep
└── README.md
```

After (in-place, no output directory):

```
my-bicep-project/
├── bricks.json          # Generated metadata
├── main.bicep           # Original files remain
├── modules/
│   ├── storage.bicep
│   └── networking.bicep
└── README.md
```

After (with output directory `--output ./dist`):

```
my-bicep-project/
├── main.bicep               # Original files untouched
├── modules/
│   ├── storage.bicep
│   └── networking.bicep
├── README.md
└── dist/
    ├── bricks.json          # Generated metadata
    └── src/
        └── bicep/           # Your files (copied)
            ├── main.bicep
            └── modules/
                ├── storage.bicep
                └── networking.bicep
```

### Test locally

Verify your package works before publishing:

```bash
# Dependency tree only (skips Azure what-if)
bricks run . --dry

# With custom properties
bricks run . --dry --props-file properties.json
```

The `--dry` flag creates a dependency tree without running the Azure deployment plan. Omit `--dry` to run a full `what-if` preview against Azure.

***

> The sections below explain how Bluebricks maps your code to inputs, outputs, and operations under the hood. Everything here is optional reading. To get started, head to [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md).

## Inputs

### What becomes an input

Bicep `param` declarations map to `props` in `bricks.json`. During publishing, Bluebricks compiles your Bicep to an ARM template (via `bicep build --stdout`) and extracts parameters automatically.

{% hint style="info" %}
Bluebricks always injects two parameters: `location` (Azure region) and `resourceGroup` (resource group name). You do not need to declare these in `bricks.json`; they are added automatically.
{% endhint %}

**Type mapping:**

<table><thead><tr><th width="180">Bicep type</th><th width="180">bricks.json type</th><th>Notes</th></tr></thead><tbody><tr><td><code>string</code></td><td><code>string</code></td><td></td></tr><tr><td><code>int</code></td><td><code>number</code></td><td></td></tr><tr><td><code>bool</code></td><td><code>boolean</code></td><td></td></tr><tr><td><code>array</code></td><td><code>list</code></td><td></td></tr><tr><td><code>object</code></td><td><code>map</code></td><td></td></tr><tr><td><code>@secure() string</code></td><td><code>string</code> (sensitive)</td><td>Marked as sensitive; never shown in diffs</td></tr><tr><td><code>@secure() object</code></td><td><code>map</code> (sensitive)</td><td>Marked as sensitive; never shown in diffs. See known issue below</td></tr><tr><td>Typed arrays (<code>int[]</code>, <code>string[]</code>)</td><td><code>list</code></td><td>Compiled to generic <code>array</code> in ARM JSON; element type information is not preserved</td></tr></tbody></table>

{% hint style="warning" %}
Parameters with Bicep expressions as defaults (e.g., `[resourceGroup().location]`) are skipped during extraction because they cannot be represented as static values.
{% endhint %}

{% hint style="warning" %}
`@secure() object` parameters are not correctly mapped to `map` in all code paths. If you use `@secure() object`, verify the generated `bricks.json` has the correct type after publishing.
{% endhint %}

**Example:**

```bicep
@description('Azure region')
param location string = 'East US'

@description('Storage account name')
param storageAccountName string

@secure()
@description('Admin password')
param adminPassword string
```

Becomes in `bricks.json`:

```json
{
  "props": {
    "location": {
      "type": "string",
      "default": "East US",
      "description": "Azure region"
    },
    "storageAccountName": {
      "type": "string",
      "description": "Storage account name"
    },
    "adminPassword": {
      "type": "string",
      "sensitive": true,
      "description": "Admin password"
    }
  }
}
```

### How inputs are delivered at runtime

All props are passed as Azure deployment parameters. Secrets are merged separately and never shown in diffs.

## Outputs

### What becomes an output

Bicep `output` declarations map to `outs` in `bricks.json`:

```bicep
output storageAccountName string = storageAccount.name
output storageAccountId string = storageAccount.id
```

After a successful apply, Bluebricks captures deployment outputs from Azure. During planning, output keys appear as placeholders until apply sets real values.

### Referencing outputs downstream

In a blueprint, reference a Bicep output from another package using `Data.azure_storage.storageAccountId`.

## Supported operations

<table><thead><tr><th width="149.66015625">Operation</th><th>What happens</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Plan</strong></td><td>Runs <code>az deployment what-if</code> to preview resource changes</td><td>Mode (Complete/Incremental) affects which changes are shown</td></tr><tr><td><strong>Apply</strong></td><td>Executes <code>az deployment create</code> with the configured mode</td><td>Waits for deployment completion</td></tr><tr><td><strong>Plan Destroy</strong></td><td>Previews resources that will be removed</td><td>Always uses Complete mode regardless of artifact configuration</td></tr><tr><td><strong>Apply Destroy</strong></td><td>Deploys an empty template in Complete mode to remove all resources in the resource group</td><td>Always uses Complete mode; also deletes the Azure deployment object and clears state</td></tr></tbody></table>

## Deployment scope

Bicep deployments in Bluebricks run at the **resource group** scope. Bluebricks automatically provisions a resource group for each environment and executes all deployments against it. Subscription-level, management-group-level, and tenant-level scopes are not supported.

{% hint style="info" %}
If your Bicep template uses `targetScope = 'subscription'`, refactor it to deploy at the resource group level before publishing to Bluebricks.
{% endhint %}

## Deployment modes

Bicep artifacts support two deployment modes that control resource lifecycle behavior: **Complete** (default) deletes resources not in the template, while **Incremental** preserves existing resources. Choose based on whether Bluebricks owns the entire resource group.

For a full comparison with decision matrix and configuration examples, see [Deployment Modes](/docs/orchestration/packages/artifacts-overview/bicep/bicep-deployment-modes.md).

## Best practices

* Keep the main template in `main.bicep` and use `modules/` for reusable components
* Provide sensible defaults and include `@description()` decorators on all parameters
* Use `@secure()` for sensitive parameters (passwords, connection strings)
* Only output values needed by downstream packages
* Use Complete mode with auto-generated resource groups for clean lifecycle management
* Use Incremental mode when deploying to shared or user-provided resource groups

## See also

* [Deployment Modes](/docs/orchestration/packages/artifacts-overview/bicep/bicep-deployment-modes.md): Complete vs Incremental mode for Bicep
* [Creating Artifacts](/docs/orchestration/packages/artifacts-overview/creating-artifacts.md): general CLI publishing workflow
* [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md): compose artifacts into blueprints


---

# 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/orchestration/packages/artifacts-overview/bicep.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.