Github Actions

Overview

The Bluebricks GitHub Actions integration lets you run any Bricks CLI command directly from your GitHub workflows. Using the official bluebricks-co/bricks-action GitHub Action, you can:

• Bump and publish artifact and blueprint versions

• Detect and respond to changes in your IaC

• Deploy infrastructure to Bluebricks collections

• Automate approvals, promotions, and notifications as part of CI/CD

This keeps Bluebricks as the orchestration layer for your infrastructure, while GitHub remains the system of record for code and pipelines.

Official Bricks CLI Action

---

Core Capabilities

The Bricks GitHub Action provides:

• Full Bricks CLI coverage – run any supported Bricks CLI command (updateci, install, bprint, etc.)

• Automatic version management – detect changes and bump artifact/blueprint versions (patch, minor, major, or auto)

• Blueprint publishing – update and publish blueprints directly from workflow runs

• Deployment integration – trigger Bluebricks deployments as part of your pipeline

• Git operations – commit, push, and create PRs for version changes

• Dry-run support – simulate changes (e.g., on PRs) without publishing or deploying

---

How to create a workflow with Bricks CLI Github Action

1. Create a new workflow and choose to set up a workflow yourself

   
2. Search for Bluebricks

   
3. Choose Bricks CLI Action to access the listing

   
4. Create you workflow and commit changes

---

Basic Usage

Add the Bricks Action to your workflow:

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Bricks CLI
        uses: bluebricks-co/[email protected]
        with:
          command: 'install'
          file: './deployments/main.yaml'
          env: 'staging'
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The command input determines which Bricks CLI command runs (e.g., updateci, install).

---

Example: Update Artifacts and Blueprints on PR

Use updateci to detect changes and bump versions when a pull request is opened or approved:

name: Update Artifacts and Blueprints on PR

on:
  pull_request:
    types: [opened, synchronize, reopened]
  pull_request_review:
    types: [submitted]

permissions:
  id-token: write
  contents: write
  pull-requests: write

jobs:
  updateci:
    runs-on: ubuntu-latest
    if: |
      (github.event_name == 'pull_request') ||
      (github.event_name == 'pull_request_review' && github.event.review.state == 'approved')

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.head.ref }}

      - name: Run updateci Command
        uses: bluebricks-co/[email protected]
        with:
          command: 'updateci'
          artifacts-folder: 'bluebricks/packages'
          blueprints-folder: 'bluebricks/blueprints'
          artifact-bump: 'patch'
          blueprint-bump: 'patch'
          base: '${{ github.base_ref }}'
          api-key: ${{ secrets.BRICKS_API_KEY }}
          flags: ${{ github.event_name == 'pull_request' && '--dry' || '' }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This pattern is ideal for automatic versioning + review, using dry-run mode on PRs.

---

Example: Deploy Infrastructure with Install

Use the install command to generate plans and apply deployments from GitHub Actions:

name: Deploy Infrastructure

on:
  pull_request:
    paths:
      - 'deployments/**'
  workflow_dispatch:
    inputs:
      collection:
        description: 'Target collection'
        required: true
        default: 'staging'

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

      - name: Deploy with Bricks
        uses: bluebricks-co/[email protected]
        with:
          command: 'install'
          file: './deployments/main.yaml'
          env: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.collection || 'staging' }}
          plan-only: ${{ github.event_name == 'pull_request' }}
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Common pattern:

• PRs → plan-only: true for review This will create an MD file of the plan and display it once a PR is submitted

  
• Manual or branch pushes → full apply to a target collection

---

Publishing Blueprints with GitHub Actions

A typical blueprint publishing workflow triggers on changes to the bluebricks/** folder:

name: Publish Blueprint

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

permissions:
  id-token: write
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Publish Blueprint
        uses: bluebricks-co/[email protected]
        with:
          command: 'updateci'
          artifacts-folder: 'bluebricks/packages'
          blueprints-folder: 'bluebricks/blueprints'
          artifact-bump: 'patch'
          blueprint-bump: 'patch'
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This automatically:

• Detects changes

• Bumps versions

• Updates dependencies

• Commits and pushes version changes back to the repo

---

Inputs (High-Level)

Global

• command – (Required) Bricks CLI command to run (e.g., updateci, install, bprint).

Common for updateci

• artifacts-folder – Path to artifacts source (e.g., bluebricks/packages).

• blueprints-folder – Path to blueprints (e.g., bluebricks/blueprints).

• artifact-bump / blueprint-bump – Version bump type (patch, minor, major, auto).

• output – Dependency graph format (ascii or json).

• api-key – Bluebricks API key (from secrets).

• flags – Extra CLI flags (e.g., --dry, --verbose).

Common for install

• file – Path to deployment manifest YAML.

• env – Collection slug.

• plan-only – Whether to plan without applying.

• set-slug – Custom deployment slug (optional).

• api-key – Bluebricks API key.

---

Outputs

For the updateci command, the following outputs are available:

• has_changes : Whether any versions were updated.

• changes_summary : Summary of version and dependency changes.

• dependency_graph : ASCII or JSON dependency graph.

For the install command, the following outputs are available:

• deployment_plan : Detailed deployment plan with resources to change.

• plan_id : Unique identifier for the generated plan.

you can consume outputs in later steps, for example:

Example:

- name: Publish Blueprint
  id: publish
  uses: bluebricks-co/[email protected]
  with:
    command: 'updateci'
    # ...

- name: Process Results
  run: |
    echo "Has changes: ${{ steps.publish.outputs.has_changes }}"
    echo "Changes summary: ${{ steps.publish.outputs.changes_summary }}"
    echo "Dependency graph: ${{ steps.publish.outputs.dependency_graph }}"

---

Prerequisites & Secrets

• BRICKS_API_KEY

  • A valid Bluebricks API key stored as a GitHub Actions secret (e.g., BRICKS_API_KEY).

• GITHUB_TOKEN

  • The built-in GITHUB_TOKEN is used for commits, pushes, and PR interaction.

• Organization Secrets

  For multiple repositories, use organization secrets:

  1. Go to your GitHub organization

  2. Navigate to Settings > Secrets and variables > Actions

  3. Add organization-level secrets

  4. Configure repository access

• Permissions If you specify workflow permissions you must add these: contents: write pull-requests: write

• Repository structure

  • Recommended folders:

    • bluebricks/packages – artifact source

    • bluebricks/blueprints – blueprint definitions

    • deployments/ – deployment manifest files

my_blueprint-repo/
├── .github/
│   └── workflows/
│       ├── publish.yml
│       ├── deploy-staging.yml
│       └── deploy-production.yml
├── bluebricks/
│   ├── packages/          # Artifact source code
│   │   ├── terraform/
│   │   ├── helm/
│   │   └── cloudformation/
│   └── blueprints/       # Blueprint configurations
│       ├── staging/
│       └── production/
├── deployments/          # Deployment manifests
│   ├── staging.yaml
│   └── production.yaml
└── README.md

For multi-repo setups, consider using Organization Secrets to share the same BRICKS_API_KEY across repositories.

---

Advanced Patterns

You can combine the Bricks Action with standard GitHub Actions features to build richer workflows:

• Multi-collection pipelines – Decide collection based on branch (main → production, develop → staging).

• Matrix publishing – Publish to multiple collections or strategies in parallel.

• Scheduled publishing – Use schedule: to publish on a weekly or nightly cadence.

• Approval gates – Use GitHub Collections with required approvals for production publishing.

• Notifications – Add Slack or email steps that consume has_changes or job status to notify teams on success/failure.

Example: Multi-Collection Publishing

name: Multi-Collection Blueprint Publishing

on:
  push:
    branches: [main, develop, staging]
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch:
    inputs:
      collection:
        description: 'Target collection'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

permissions:
  id-token: write
  contents: write
  pull-requests: write

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      has-artifacts: ${{ steps.changes.outputs.artifacts }}
      has-blueprints: ${{ steps.changes.outputs.blueprints }}
      collection: ${{ steps.env.outputs.collection }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Detect changes
        uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            artifacts:
              - 'bluebricks/packages/**'
            blueprints:
              - 'bluebricks/blueprints/**'

      - name: Determine collection
        id: env
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            echo "collection=${{ github.event.inputs.collection }}" >> $GITHUB_OUTPUT
          elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
            echo "collection=production" >> $GITHUB_OUTPUT
          elif [ "${{ github.ref }}" = "refs/heads/develop" ]; then
            echo "collection=staging" >> $GITHUB_OUTPUT
          else
            echo "collection=development" >> $GITHUB_OUTPUT
          fi

  publish:
    runs-on: ubuntu-latest
    needs: detect-changes
    if: needs.detect-changes.outputs.has-artifacts == 'true' || needs.detect-changes.outputs.has-blueprints == 'true'

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.head.ref || github.ref }}

      - name: Update and Publish
        uses: bluebricks-co/[email protected]
        with:
          command: 'updateci'
          artifacts-folder: 'bluebricks/packages'
          blueprints-folder: 'bluebricks/blueprints'
          artifact-bump: 'patch'
          blueprint-bump: 'patch'
          base: '${{ github.base_ref }}'
          api-key: ${{ secrets.BRICKS_API_KEY }}
          flags: ${{ github.event_name == 'pull_request' && '--dry' || '' }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy to Collection
        if: github.event_name == 'push' && needs.detect-changes.outputs.collection != 'development'
        uses: bluebricks-co/[email protected]
        with:
          command: 'install'
          file: './deployments/main.yaml'
          env: ${{ needs.detect-changes.outputs.collection }}
          plan-only: false
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Example: Conditional Publishing with Matrix

name: Matrix Blueprint Publishing

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

permissions:
  id-token: write
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - collection: staging
            bump-type: patch
          - collection: production
            bump-type: minor

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Publish Blueprint
        uses: bluebricks-co/[email protected]
        with:
          command: 'updateci'
          artifacts-folder: 'bluebricks/packages'
          blueprints-folder: 'bluebricks/blueprints'
          artifact-bump: ${{ matrix.bump-type }}
          blueprint-bump: ${{ matrix.bump-type }}
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy to ${{ matrix.collection }}
        uses: bluebricks-co/[email protected]
        with:
          command: 'install'
          file: './deployments/${{ matrix.collection }}.yaml'
          env: ${{ matrix.collection }}
          plan-only: false
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

---

Customization & Precedence

Bricks CLI configuration follows this precedence:

1. GitHub Action inputs

2. Collection variables

3. Bricks config file (e.g., config.yaml)

4. Internal defaults

This gives you flexibility to:

• Keep most configuration in code

• Override behavior per workflow or job with inputs and flags

• Reuse a shared configuration file where it makes sense

---

Best Practices

Workflow Design

• Use path filters to trigger only on relevant changes

• Implement proper error handling and rollback procedures

• Use collection-specific configurations

• Add status checks for pull requests

Security

• Store API keys in GitHub Secrets

• Use least-privilege permissions

• Review workflow changes carefully

• Monitor workflow execution logs

Performance

• Use matrix strategies for parallel execution

• Cache dependencies when possible

• Optimize workflow triggers

• Monitor workflow execution time