Plan a Deployment

Use bricks install --plan-only to preview infrastructure changes before applying them.

Prerequisites

• Bluebricks CLI installed

• Authenticated with Bluebricks (bricks login)

• Existing collection (environment)

• Package to deploy (local blueprint or published package)

Quick Start

1. Plan a deployment (plan-only):

   bricks install @myorg/postgres --collection production --plan-only

2. Plan with custom properties:

   bricks install @myorg/postgres --collection production --plan-only --props-file properties.json

3. Plan with deployment manifest:

   bricks install --file deployment.yaml --plan-only

What Is Planning?

Planning is the process of:

• Analyzing changes that will be made to infrastructure

• Validating resources before creation

• Reviewing resource lifecycle (create, update, destroy)

• Previewing execution plan without making changes

After creating a plan, you can:

• Review it in the Bluebricks web UI

• Approve it to proceed with installation

• Cancel it if changes aren't desired

Planning Commands

Basic Plan

# Plan deployment for a published package
bricks install @myorg/postgres --collection production --plan-only

# Plan deployment for a local blueprint
bricks install ./my-blueprint --collection production --plan-only

Plan with Custom Properties

# Plan with properties file
bricks install @myorg/postgres --collection production --plan-only --props-file properties.json

# Plan with inline properties
bricks install @myorg/postgres --collection production --plan-only --props '{"vpc_cidr":"10.0.0.0/16"}'

Plan with Deployment Manifest

Create a deployment manifest file (deployment.yaml):

apiVersion: bricks/v1
kind: Deployment
metadata:
  name: my-postgres-db
spec:
  blueprint: @myorg/postgres
  version: "1.0.0"
  environment: production
  planOnly: true
  props:
    instance_type: db.t3.medium
    storage_gb: 100

Execute the plan:

bricks install --file deployment.yaml

Plan Output

The plan output shows:

• Resources to create: New infrastructure resources

• Resources to update: Existing resources that will be modified

• Resources to destroy: Resources that will be removed

• No changes: Resources that remain unchanged

After planning, view the detailed plan in the Bluebricks web UI:

Plan created successfully.
Review plan at https://app.bluebricks.co/plans

Deployment Flow

1. Create a Plan

# Create a plan without applying
bricks install @myorg/postgres --collection production --plan-only --props-file props.json

2. Review Plan

Review the plan in the web UI:

• Verify resources to be created

• Check for unexpected deletions

• Review resource modifications

• Examine dependency graph

3. Approve and Install

After reviewing the plan, approve it to proceed:

Option A: Via Web UI

• Open the plan URL

• Review all changes

• Click "Approve" to proceed with installation

Option B: Via CLI (create and auto-approve)

# Skip planning, create and auto-approve in one command
bricks install @myorg/postgres --collection production --yes --props-file props.json

Using GitHub Actions

Automate planning with the official Bricks GitHub Action:

Plan on Pull Request

name: Plan Deployments

on:
  pull_request:
    branches: [main]
    paths:
      - 'deployments/**'

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create deployment plan
        uses: bluebricks-co/bricks-action@v1
        with:
          command: install
          file: deployments/production.yaml
          plan-only: true
          api-key: ${{ secrets.BRICKS_API_KEY }}

Deploy on Merge

name: Deploy to Production

on:
  push:
    branches: [main]
    paths:
      - 'deployments/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Execute deployment
        uses: bluebricks-co/bricks-action@v1
        with:
          command: install
          file: deployments/production.yaml
          api-key: ${{ secrets.BRICKS_API_KEY }}

Matrix Deployment (Multiple Environments)

name: Deploy Multiple Environments

on:
  workflow_dispatch:
    inputs:
      plan_only:
        description: 'Generate plan only'
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: [staging, production]
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to ${{ matrix.environment }}
        uses: bluebricks-co/bricks-action@v1
        with:
          command: install
          file: deployments/${{ matrix.environment }}.yaml
          plan-only: ${{ inputs.plan_only }}
          api-key: ${{ secrets.BRICKS_API_KEY }}

Best Practices

Always Plan First

• Create a plan before applying changes

• Review plans thoroughly in the web UI

• Check for unexpected changes

• Verify resource dependencies

Property Management

• Use deployment manifest files for consistency

• Store properties files in version control

• Use separate files for different collections

• Validate property values before planning

Collection Strategy

• Plan in a development collection first

• Test changes in staging

• Apply to the production collection after thorough review

• Use CI/CD for automated planning on PRs

Approval Workflow

• Use --plan-only for manual approval workflow

• Use --yes flag only in trusted CI/CD pipelines

• Review all plans before approval

• Document approval requirements for production

Common Scenarios

Update Existing Deployment

# Plan update to existing deployment
bricks install --deployment my-postgres-db --plan-only

Create New Deployment with Custom Slug

# Plan new deployment with specific slug
bricks install @myorg/postgres --collection production --set-slug custom-db --plan-only

Non-Interactive Planning (CI/CD)

# Plan in non-interactive mode (exits after plan creation)
bricks install @myorg/postgres --collection production --plan-only --props-file props.json

See also

• Creating Environments -- environment lifecycle and run concepts

• How to Destroy Deployments -- safely tear down resources

• Deployment Status Monitoring -- track deployment progress