Building Block Runner

This repository contains the open-source meshStack Building Block Runners — processes that pick up infrastructure provisioning runs, invoke the underlying tool (Terraform, a CI/CD pipeline, or a manual process), and report the result back. Runners are a core part of meshStack, a sovereign internal developer platform where teams publish self-service infrastructure units called Building Blocks that developers can order on demand.

meshStack ships with managed runners that work out of the box — no setup required. This repository lets you deploy and operate runners yourself on your own infrastructure. We believe it is important that you can inspect exactly what runs in your environment and deploy it on your own terms — full sovereignty over the execution layer, with no black boxes.

This repository contains multiple runners, one for each supported tool:

Runner	Language	Description
tf-block-runner	Go	Executes OpenTofu plans and applies
github-block-runner	Kotlin	Triggers GitHub Actions workflows
gitlab-block-runner	Kotlin	Triggers GitLab CI pipelines
azure-devops-block-runner	Kotlin	Triggers Azure DevOps pipelines
manual-block-runner	Kotlin	No-op runner for manually managed building blocks

Running a runner

Each runner is distributed as a container image and configured via a YAML file. The general steps are:

1. Create a new Building Block Runner in meshStack and create an API key for the runner.
2. Write & configure a runner-config.yml with the meshStack API configuration.
3. Deploy the runner container on your infrastructure of choice (Kubernetes, a VM, or locally for testing).
4. Reference the new runner in the Building Block Definition of your choice.

The runner will then poll meshStack for pending runs and execute them.

For full configuration reference and deployment guides, see the meshStack documentation. We highly recommend creating a new runner via the meshStack UI as it will fully explain and generate the configuration for you.

Support

Building Block Runners are part of the commercial meshStack SaaS platform. If you are a customer you can open a ticket through support@meshcloud.io. Building Block Runners fall under the SLA, and we will help you out as quickly as we can.

If you have any community or open-source questions, you can open a GitHub issue right here.

For general information about the meshStack platform and Building Blocks, see the meshStack documentation.

Repository structure

This repository uses two separate build systems in parallel:

• Go modules (run-controller, tf-block-runner, go-meshapi-client) are managed via a Go workspace. Run go work sync from the root if module references change.
• JVM modules (block-runner-core, github-block-runner, gitlab-block-runner, azure-devops-block-runner, manual-block-runner) are managed via Gradle.

Alongside the runners, the repository contains shared modules:

• run-controller — Kubernetes controller that executes Building Block Runs via Kubernetes Jobs, supporting all runner implementations with parallel execution
• block-runner-core — shared Kotlin library used by all JVM-based runners
• go-meshapi-client — shared Go client for the meshcloud API

Common tasks are available via make:

make help

Health endpoint

Every runner exposes a /healthz endpoint that returns 200 OK with body OK. This is intended for liveness probes in container orchestrators.

Each runner listens on a dedicated default port to avoid conflicts when running multiple runners locally alongside meshStack (which defaults to port 8080):

Runner	Default port
tf-block-runner	8100
azure-devops-runner	8101
github-block-runner	8102
gitlab-block-runner	8103
manual-block-runner	8104

Override the port with the PORT environment variable:

PORT=9000 go run .           # tf-block-runner
PORT=9000 ./gradlew bootRun  # JVM runners

If you are running a runner through a Docker image, it will default to PORT=8080 as well. You can still decide to override the PORT environment variable in your environment.

Development

Prerequisites

• Go 1.22+
• JDK 21+

Build and test (Go)

make test          # run all Go tests
make fmt           # format Go code
make vet           # run go vet
make tidy          # tidy go modules
make work-sync     # sync go.work entries

Build and test (JVM)

./gradlew build
./gradlew test

Run locally

make start-run-controller    # start run-controller
make start-tf-block-runner   # start tf-block-runner

See the individual module READMEs for module-specific instructions:

• run-controller/README.md
• tf-block-runner/README.md

Release

Releases are created from main by tagging the current commit and pushing the tag:

git checkout main
git pull
git tag v1.2.3
git push origin v1.2.3

Contributing

For bugs, please reach out via support@meshcloud.io — runner issues are covered under the meshStack SLA and will be handled as quickly as possible.

For feature requests, open one at our public feedback board

Pull requests are welcome, but reaching out through the above channels first is preferred — it avoids duplicate effort and ensures your contribution aligns with the roadmap. For larger changes, please get in touch before investing significant time.

Security

If you discover a security vulnerability, please do not open a public issue. See SECURITY.md for responsible disclosure instructions.