Publish via GitHub Actions

Automate blueprint publishing using GitHub Actions and the official Bricks Action for seamless CI/CD integration.

Prerequisites

• GitHub repository with blueprint code

• Bricks API key stored in GitHub Secrets

• GitHub Actions enabled for the repository

• Understanding of GitHub Actions workflows

Bricks Action Overview

The Bricks Action provides seamless integration between GitHub Actions and Bricks CLI commands.

Key Features

• Version bumping: Automatic version management for artifacts and blueprints

• Blueprint updates: Update and publish blueprints automatically

• Deployment integration: Deploy infrastructure as part of the workflow

• Git operations: Automatic commits and pushes for version updates

Basic Publishing Workflow

Simple Blueprint Publishing

Create .github/workflows/publish.yml:

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/bricks-action@v1.2.0
        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 }}

Advanced Publishing Workflows

Multi-Environment Publishing

name: Multi-Environment Blueprint Publishing

on:
  push:
    branches: [main, develop, staging]
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        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 }}
      environment: ${{ steps.env.outputs.environment }}
    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 environment
        id: env
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            echo "environment=${{ github.event.inputs.environment }}" >> $GITHUB_OUTPUT
          elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
            echo "environment=production" >> $GITHUB_OUTPUT
          elif [ "${{ github.ref }}" = "refs/heads/develop" ]; then
            echo "environment=staging" >> $GITHUB_OUTPUT
          else
            echo "environment=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/bricks-action@v1.2.0
        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 Environment
        if: github.event_name == 'push' && needs.detect-changes.outputs.environment != 'development'
        uses: bluebricks-co/bricks-action@v1.2.0
        with:
          command: 'install'
          file: './deployments/main.yaml'
          env: ${{ needs.detect-changes.outputs.environment }}
          plan-only: false
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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:
          - environment: staging
            bump-type: patch
          - environment: production
            bump-type: minor

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

      - name: Publish Blueprint
        uses: bluebricks-co/bricks-action@v1.2.0
        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.environment }}
        uses: bluebricks-co/bricks-action@v1.2.0
        with:
          command: 'install'
          file: './deployments/${{ matrix.environment }}.yaml'
          env: ${{ matrix.environment }}
          plan-only: false
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Workflow Features

Automatic Version Management

The updateci command automatically:

• Detects changes in artifacts and blueprints

• Bumps versions based on change type (patch, minor, major)

• Updates dependencies between artifacts and blueprints

• Commits changes back to the repository

• Creates pull requests for review (optional)

Dry Run Mode

For pull requests, enable dry-run mode:

flags: ${{ github.event_name == 'pull_request' && '--dry' || '' }}

This shows what changes would be made without actually publishing.

Output Handling

Access workflow outputs for further processing:

- name: Publish Blueprint
  id: publish
  uses: bluebricks-co/bricks-action@v1.2.0
  with:
    command: 'updateci'
    # ... other inputs

- 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 }}"

Configuration Options

Version Bump Strategies

# Patch version bump (1.0.0 → 1.0.1)
artifact-bump: 'patch'
blueprint-bump: 'patch'

# Minor version bump (1.0.0 → 1.1.0)
artifact-bump: 'minor'
blueprint-bump: 'minor'

# Major version bump (1.0.0 → 2.0.0)
artifact-bump: 'major'
blueprint-bump: 'major'

# Auto-detect based on changes
artifact-bump: 'auto'
blueprint-bump: 'auto'

Output Formats

# ASCII dependency graph (default)
output: 'ascii'

# JSON dependency graph
output: 'json'

Custom Flags

# Additional flags for updateci command
flags: '--verbose --force --no-commit'

Repository Structure

Organize your repository for optimal workflow performance:

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

GitHub Secrets Setup

Required Secrets

1. BRICKS_API_KEY: Your Bluebricks API key

2. GITHUB_TOKEN: Automatically provided by GitHub

Setting Up Secrets

1. Go to your GitHub repository

2. Navigate to Settings > Secrets and variables > Actions

3. Click "New repository secret"

4. Add your Bluebricks API key as BRICKS_API_KEY

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

Advanced Patterns

Scheduled Publishing

name: Scheduled Blueprint Publishing

on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM
  workflow_dispatch:

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

      - name: Publish Blueprint
        uses: bluebricks-co/bricks-action@v1.2.0
        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 }}

Approval Gates

name: Blueprint Publishing with Approval

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: write

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

      - name: Publish Blueprint
        uses: bluebricks-co/bricks-action@v1.2.0
        with:
          command: 'updateci'
          artifacts-folder: 'bluebricks/packages'
          blueprints-folder: 'bluebricks/blueprints'
          artifact-bump: 'minor'
          blueprint-bump: 'minor'
          api-key: ${{ secrets.BRICKS_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Monitoring and Notifications

Slack Notifications

- name: Notify Slack
  if: always()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    channel: '#deployments'
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}
    fields: repo,message,commit,author,action,eventName,ref,workflow

Email Notifications

- name: Send Email
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 587
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: 'Blueprint Publishing Failed'
    to: '[e-mail]'
    from: 'GitHub Actions'
    body: 'Blueprint publishing failed for ${{ github.repository }}'

Best Practices

Workflow Design

• Use path filters to trigger only on relevant changes

• Implement proper error handling and rollback procedures

• Use environment-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

See also

• GitHub integration -- connecting Bluebricks to GitHub

• How to Publish with CLI -- manual CLI publishing

• How to Create API Keys -- setting up API keys for automation