# Github Actions

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](https://github.com/marketplace/actions/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<br>

   <figure><img src="/files/VbENCappIzndMAQ58D7P" alt=""><figcaption></figcaption></figure>
2. Search for Bluebricks<br>

   <figure><img src="/files/nxZwYPf59RlQSBEg4AWD" alt=""><figcaption></figcaption></figure>
3. Choose Bricks CLI Action to access the listing<br>

   <figure><img src="/files/iK0gddFdtjzeWs8An6T6" alt=""><figcaption></figcaption></figure>
4. Create your workflow and commit changes

***

### Basic Usage

Add the Bricks Action to your workflow:

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

      - name: Run Bricks CLI
        uses: bluebricks-co/bricks-action@v1.2.0
        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:

```yaml
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/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 }}
```

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:

```yaml
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/bricks-action@v1.2.0
        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<br>

  <figure><img src="/files/wsDGn8hDV5WFL6iGVl0l" alt="" width="375"><figcaption></figcaption></figure>
* **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:

```yaml
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 }}
```

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:

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

```yaml
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/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 Collection
        if: github.event_name == 'push' && needs.detect-changes.outputs.collection != 'development'
        uses: bluebricks-co/bricks-action@v1.2.0
        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

```yaml
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/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.collection }}
        uses: bluebricks-co/bricks-action@v1.2.0
        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

#### Example: Scheduled Publishing

```yaml
name: Scheduled Blueprint Publishing

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

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

#### Example: Approval Gates

Use [GitHub Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) with required reviewers to gate production publishing:

```yaml
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 from designated reviewers

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

#### Example: Slack Notifications

Add a notification step to report publishing results to your team:

```yaml
- 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
```

***

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/integrations/githubactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.