Lifecycle and Execution

How Generic artifacts execute across deployment stages, with per-stage configuration and smart execution caching.

Generic artifacts support per-stage configuration and smart execution caching. This page covers lifecycle overrides, auto-injected environment variables, and the rules that determine when your container runs or is skipped.

Lifecycle configuration

The lifecycle key in bricks.json lets you override the default container configuration for individual deployment stages. Each stage (plan, apply, destroy) can specify its own image, command, args, env vars, or skip the stage entirely.

When to use lifecycle config vs. environment variable detection

Approach	Best for
Lifecycle config	Different CLI arguments per stage, different images, skipping stages
BRICKS_ACTION detection	A single script that branches on the current stage

Basic structure

{
  "native": {
    "type": "generic",
    "image": "custom/tool:1.0",
    "command": ["tool"],
    "args": ["default-action"],
    "lifecycle": {
      "plan": {
        "args": ["plan", "--detailed"]
      },
      "apply": {
        "args": ["apply", "--auto-approve"]
      },
      "destroy": {
        "args": ["destroy", "--force"]
      }
    }
  }
}

Phase fields

Each phase (plan, apply, destroy) supports these fields:

Field	Type	Description	Default
image	string	Container image for this phase	Inherits from native.image
command	array	Command to execute	Inherits from native.command
args	array	Command arguments	Inherits from native.args
env_vars	object	Environment variables (merged with native)	Inherits from native.env_vars
skip	boolean	Skip execution for this phase (plan and destroy only)	false

Phase fields override the native configuration. If a field is not specified in the phase, it falls back to the native value. Environment variables are merged, with phase values taking precedence.

Skipping stages

Set skip: true to prevent the container from executing during a stage. This is supported for plan and destroy only: apply cannot be skipped.

{
  "native": {
    "type": "generic",
    "image": "python:3.11-slim",
    "command": ["python"],
    "args": ["healthcheck.py"],
    "lifecycle": {
      "destroy": {
        "skip": true
      }
    }
  }
}

Common use cases for skipping:

• Skip destroy: read-only scripts, health checks, monitoring tools

• Skip plan: operations that don't benefit from a preview phase

When a stage is skipped, the container does not execute, but the deployment stage still completes successfully.

Environment variables

Bluebricks injects the following environment variables into every Generic artifact execution:

BRICKS_ACTION

The current deployment stage. Your script can use this to branch behavior without lifecycle config.

Value	Stage
plan	Preview/planning phase
apply	Create or update operation
plan-destroy	Preview before destruction
destroy	Cleanup/removal operation

import os

action = os.environ.get('BRICKS_ACTION')

if action == 'plan':
    validate_configuration()
elif action == 'apply':
    deploy_resources()
elif action in ('plan-destroy', 'destroy'):
    cleanup_resources()

BRICKS_STATE

Base64-encoded JSON containing the previous deployment's output. Available when state exists from a prior execution.

import os, json, base64

state_b64 = os.environ.get('BRICKS_STATE')
if state_b64:
    state = json.loads(base64.b64decode(state_b64))
    previous_outputs = state.get('output', {})
    resource_id = previous_outputs.get('resource_id')

BRICKS_JOB_ID

UUID identifying the current job execution. Useful for logging and correlation.

job_id = os.environ.get('BRICKS_JOB_ID')
print(f"[{job_id}] Starting operation")

Execution behavior

Generic artifacts use input tracking to decide when to run your container:

Container executes when:

• First deployment: no previous outputs exist

• Inputs change: props or secrets are modified

• Version changes: the package version is bumped

• Forced execution: using techniques like the now() function

Container skips when:

• Inputs unchanged: props and secrets are identical to the previous run

• Outputs exist: previous execution results are cached

• Same version: the package version hasn't changed

Container code changes do NOT trigger re-execution. If you fix a bug in your script but don't change any inputs or the package version, existing deployments won't pick up the fix. You must bump the version or change an input to force re-execution.

Forcing execution

When you need a Generic artifact to run on every deployment regardless of input changes (e.g., health checks, cleanup scripts), use the now() function to ensure inputs always differ:

{
  "props": {
    "api_endpoint": {
      "type": "string",
      "description": "API endpoint to check"
    },
    "force_run": {
      "type": "string",
      "description": "Timestamp to force execution",
      "value": "now().Format('2006-01-02T15:04:05Z')"
    }
  }
}

Because force_run changes on every deployment, the input hash always differs and the container always executes.

Alternative: bump the package version to force a single re-execution.

Example: database migration

A complete example showing lifecycle configuration for a database migration tool:

{
  "name": "db-migration",
  "version": "1.0.0",
  "native": {
    "type": "generic",
    "image": "migrate/migrate:latest",
    "command": ["migrate"],
    "args": [
      "-source", "file:///workspace/migrations",
      "-database", "postgres://...",
      "up"
    ],
    "lifecycle": {
      "plan": {
        "args": [
          "-source", "file:///workspace/migrations",
          "-database", "postgres://...",
          "version"
        ]
      },
      "destroy": {
        "args": [
          "-source", "file:///workspace/migrations",
          "-database", "postgres://...",
          "down"
        ]
      }
    }
  },
  "props": {
    "database_url": {
      "type": "string",
      "description": "PostgreSQL connection string"
    }
  }
}

Stage	What happens
Plan	Checks the current migration version
Apply	Runs migrations up
Destroy	Runs migrations down