Bicep

Bicep reference: deployment modes, parameter mapping, outputs capture, and Azure authentication

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.

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

For a complete guide to how inputs and outputs work across all IaC tools, see Inputs & Outputs.

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.

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.

bricks.json reference

Field	Required	Description
type	Yes	"bicep"
path	Yes	Directory containing the Bicep template files
mode	No	Deployment mode: "Complete" (default) or "Incremental". See Deployment Modes

Example bricks.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: 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:

   cd ~/my-bicep-project

2. Run blueprint prepare:

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

   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:

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

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.

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.

Type mapping:

Bicep type	bricks.json type	Notes
string	string
int	number
bool	boolean
array	list
object	map
@secure() string	string (sensitive)	Marked as sensitive; never shown in diffs
@secure() object	map (sensitive)	Marked as sensitive; never shown in diffs. See known issue below
Typed arrays (int[], string[])	list	Compiled to generic array in ARM JSON; element type information is not preserved

Parameters with Bicep expressions as defaults (e.g., [resourceGroup().location]) are skipped during extraction because they cannot be represented as static values.

@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.

Example:

@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:

{
  "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:

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

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

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.

If your Bicep template uses targetScope = 'subscription', refactor it to deploy at the resource group level before publishing to Bluebricks.

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.

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: Complete vs Incremental mode for Bicep

• Creating Artifacts: general CLI publishing workflow

• Creating Blueprints: compose artifacts into blueprints