Fully meshStack-Managed GitOps for Building Blocks
Jelle den Burger
Problem / Use Case
Building Block Definitions can already be backed by a Git repo, but the git experience today has several gaps that force manual steps and create traps:
- BBDs pin to a "Git Reference" that can be a floating branch name. Merging a feature branch into main does not update the BBD, it silently keeps running the old branch until someone remembers to repoint it.
- There is no way to see what a change to a Building Block's Terraform code will actually do before it merges or before it upgrades a live instance. Every plan is only visible at apply time, after the fact.
- Creating a new Building Block Definition version after a code change is a manual step today.
- Repo access is limited to inline SSH keys, there is no GitHub App or PAT-based integration, so meshStack cannot receive repository events (PRs, releases) or post status back to GitHub.
As a result, teams cannot get a normal "branch, PR, merge, release" workflow for their Building Blocks the way they would for any other Terraform module, entirely without needing their own CI/CD pipeline to plug meshStack in.
Proposed Solution
Introduce a meshStack GitHub App (or equivalent for other Git providers) integration that drives the whole Building Block lifecycle without a platform engineer needing to write or maintain any GitHub Actions/CI of their own:
- Immutable version pinning: released BBD versions must pin to a commit hash or tag, never a floating branch. Warn or block promotion out of draft if the Git Reference doesn't match a hash/tag pattern.
- PR-time plan check: on PR opened/updated, meshStack runs a plan-only Building Block run on its own infrastructure against a dedicated canary instance (representative dummy inputs), and posts the result back as a GitHub Check Run under the meshStack App's identity. No customer-authored workflow file involved.
- Automatic BBD versioning: on merge or GitHub Release published, meshStack automatically creates the next Building Block Definition version pinned to the new commit/tag, no manual "create version" step.
- Traceable upgrades: when a live instance upgrades to a new BBD version, the run and its plan link back to the exact commit/tag/PR that produced it.
Known gaps to close (linking related requests already tracked):
- Floating branch references / no warning on unpinned BBDs: Building Block definition and working with branches ("stuck BB definition")
- No GitHub App / PAT-based repo authentication (needed for webhook delivery and posting check runs, beyond just cloning): Support GitHub App and Personal Access Token authentication for Building Block repo cloning