Publish via GitOps

Connect your Git repositories to automatically sync artifact updates to Bluebricks using GitHub App integration.

Prerequisites

• Git repository with artifact source code (Terraform, Helm, Bicep, etc.)

• GitHub organization or GitLab account

• Artifact source code in a dedicated directory path

How Git Sync Works

Git sync automatically updates your artifacts when code changes in your repository.

Sync Flow

1. Connect Repository: Install GitHub App and select your repository

2. Configure Sync: Specify branch and directory path containing artifact source code

3. Enable Sync: Create a Git trigger that monitors the repository

4. Automatic Updates: When code is pushed to the configured branch/path, Bluebricks automatically syncs the artifact

What Gets Synced

• Source code changes: Terraform modules, Helm charts, Bicep templates, etc.

• Git metadata: Commit hash, branch reference, repository URL

• Directory path: Exact location of artifact source code

Synced artifacts show a refresh icon in the Bluebricks UI.

Setting Up Git Sync (GitHub)

Step 1: Install GitHub App

1. In Bluebricks, open the repository sidebar:

   • Navigate to Artifacts page

   • Click an artifact to open the sidebar

   • Click "Connect to Git" or the Git icon

2. Select "Continue with GitHub"

3. Install the Bluebricks GitHub App:

   • Choose "All repositories" or select specific repositories

   • Click "Install"

   • GitHub redirects back to Bluebricks

Step 2: Select Organization and Repository

After installation, configure your repository:

1. Git Organization: Select your GitHub organization from the dropdown

2. Git Repository: Select the repository containing your artifact source code

3. Git Branch: Enter the branch name to monitor (e.g., main, develop)

4. Path: Enter the exact directory path containing the artifact source code (e.g., /bluebricks, /terraform/modules/vpc)

Step 3: Enable Sync

Click "Enable sync" to create the Git trigger. Bluebricks will:

• Monitor the specified branch and path

• Automatically sync when code is pushed

• Update artifact metadata with commit information

Repository Structure

Your repository can contain multiple artifacts in different directories:

my-repo/
├── terraform/
│   ├── vpc/              # Path: /terraform/vpc
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── subnet/           # Path: /terraform/subnet
│       ├── main.tf
│       └── variables.tf
├── helm/
│   └── nginx/            # Path: /helm/nginx
│       ├── Chart.yaml
│       └── values.yaml
└── README.md

Each artifact is synced independently based on its configured path.

Setting Up Git Sync (GitLab)

GitLab integration uses a workflow approach instead of an app installation:

1. In Bluebricks, select "Setup workflow with GitLab"

2. Follow the GitLab workflow setup instructions at: https://gitlab.com/bluebricks-dev/workflow/-/tree/main/steps/bricks

3. Configure the workflow in your GitLab repository to sync artifacts

Note: Bitbucket and Azure DevOps integrations are coming soon.

Managing Synced Artifacts

Viewing Sync Status

In the Artifacts table, synced artifacts display:

• Repository icon: Links to the Git repository folder

• Commit badge: Shows short commit SHA (click to view full commit)

• Refresh icon: Indicates artifact is synced with Git

Disabling Sync

To disable sync for an artifact:

1. Open the repository sidebar for the artifact

2. Click "Disable sync"

3. Confirm the action

Note: Disabling sync does not delete the artifact. It only stops automatic updates from the repository. The artifact remains available in Bluebricks and can be managed manually.

Reconnecting Repository

If sync is disabled, you can re-enable it:

1. Open the repository sidebar

2. Select organization, repository, branch, and path

3. Click "Enable sync"

Creating New Artifacts from Git

From the repository sidebar, you can create new artifacts directly from a repository:

1. Create artifact: Creates one artifact and closes the sidebar

2. Create & add another: Creates an artifact and keeps the sidebar open to add more artifacts from the same or different repositories

Best Practices

Repository Organization

• Dedicated directories: Keep each artifact in its own directory

• Consistent structure: Use the same directory layout across artifacts

• Single branch per environment: Use main for production, develop for development

• Clear paths: Use descriptive directory names (e.g., /terraform/vpc not /pkg1)

Git Workflow

• Feature branches: Develop changes in feature branches

• Pull requests: Review code before merging to monitored branches

• Commit messages: Write clear commit messages for traceability

• Branch protection: Protect monitored branches (main, develop) with branch rules

Path Configuration

• Exact paths: Specify the exact directory containing artifact source code

• One path per artifact: Don't sync the same path to multiple artifacts

• Root vs subdirectory: Use subdirectories for better organization (e.g., /terraform/vpc instead of /)

• Avoid wildcards: Paths should point to specific directories, not patterns

Sync Management

• Enable selectively: Only enable sync for artifacts actively developed in Git

• Disable when needed: Disable sync for stable artifacts or during major refactoring

• Monitor updates: Check commit hashes to verify sync is working

• Clean history: Keep Git history clean for easier troubleshooting

See also

• Git Repository Guide -- Git integration best practices

• GitHub integration -- connecting Bluebricks to GitHub

• GitLab integration -- connecting Bluebricks to GitLab