# How to Integrate ChaosBlade with CI/CD Pipelines: Complete Build Guide

> Integrate ChaosBlade with CI/CD pipelines using Makefile targets for consistent Go builds, cross-platform compilation, and Docker image creation on any platform.

- Repository: [ChaosBlade/chaosblade](https://github.com/chaosblade-io/chaosblade)
- Tags: how-to-guide
- Published: 2026-02-27

---

**ChaosBlade integrates with CI/CD pipelines by reusing the same Makefile targets (`make test`, `make build`, `make package`) that the upstream GitHub Actions workflow uses, enabling consistent Go builds, cross-platform compilation, and Docker image creation across any CI platform.**

ChaosBlade is a **Go-based chaos engineering CLI** (`blade`) distributed through the `chaosblade-io/chaosblade` repository. The project ships with a comprehensive build system centered on a **Makefile** that defines standardized targets for testing, cross-compilation, and packaging. By invoking these targets inside your CI runner, you can reproduce the exact validation pipeline defined in [`.github/workflows/ci.yml`](https://github.com/chaosblade-io/chaosblade/blob/main/.github/workflows/ci.yml) whether you use GitHub Actions, Jenkins, GitLab CI, or Azure Pipelines.

## Core Build Targets in the Makefile

The `Makefile` at the repository root defines the **continuous integration contract** for ChaosBlade. These targets handle dependency resolution, race-condition testing, multi-platform builds, and OCI image creation:

- **`make verify`** – Runs [`hack/verify-gofmt.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/hack/verify-gofmt.sh) and [`hack/verify-imports.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/hack/verify-imports.sh) to enforce code style and import ordering.
- **`make test`** – Executes `go test -race -coverprofile=coverage.txt` across all core packages, producing coverage reports compatible with Codecov.
- **`make build`** – Compiles the `blade` CLI for the host platform using the entry point in [`cli/main.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/main.go).
- **`make linux_amd64 MODULES=all`** – Cross-compiles the CLI and selected experiment executors (OS, K8s, JVM, Docker) for Linux AMD64.
- **`make build_linux_amd64_image`** – Uses Docker **buildx** to create an OCI image bundling the CLI and all selected executors via `build/image/blade/Dockerfile`.
- **`make package`** – Archives the compiled binaries and YAML experiment specs into a versioned tarball ready for release.

All targets are **idempotent** and derive versioning from [`scripts/version.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/scripts/version.sh), which extracts the `BLADE_VERSION` from Git tags or environment variables.

## GitHub Actions Implementation

The repository provides a complete reference implementation in [`.github/workflows/ci.yml`](https://github.com/chaosblade-io/chaosblade/blob/main/.github/workflows/ci.yml). The workflow orchestrates the Makefile targets across a matrix of platforms (Linux AMD64/ARM64, macOS AMD64/ARM64).

Key stages include:

**Dependency Caching** – The workflow caches `~/.cache/go-build` and `~/go/pkg/mod` using `actions/cache` to speed up subsequent runs.

**Static Analysis** – The `make verify` step enforces Go formatting standards before any compilation occurs.

**Test Execution** – `make test` runs unit tests with the `-race` flag enabled, catching concurrency issues early in the pipeline.

**Multi-Platform Builds** – The workflow invokes `make build` for each OS/architecture combination, storing binaries as job artifacts.

**Docker Image Creation** – For Linux targets, `make build_linux_amd64_image MODULES=all` produces a compressed image using UPX, ready for publishing toGHCR or Docker Hub.

## Jenkins Pipeline Integration

For Jenkins users, the following Declarative Pipeline mirrors the GitHub Actions logic by invoking the same Makefile targets:

```groovy
pipeline {
    agent any
    environment {
        GO_VERSION = '1.25'
    }
    stages {
        stage('Checkout') {
            steps { checkout scm }
        }
        stage('Setup Go') {
            steps {
                sh '''
                curl -sSL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz | tar -C /usr/local -xz
                export PATH=/usr/local/go/bin:$PATH
                go version
                '''
            }
        }
        stage('Verify') {
            steps { sh 'make verify' }
        }
        stage('Test') {
            steps { sh 'make test' }
        }
        stage('Build Linux AMD64 Image') {
            steps { sh 'make build_linux_amd64_image MODULES=all' }
        }
        stage('Archive artifacts') {
            steps { 
                archiveArtifacts artifacts: 'target/chaosblade-*.tgz' 
            }
        }
    }
}

```

This pipeline assumes the Jenkins agent has Docker installed for the image build stage. The `target/` directory contains the versioned tarball generated by `make package`.

## GitLab CI Configuration

GitLab CI can implement the same workflow using a Go image and cache directives:

```yaml
image: golang:1.25

variables:
  GOFLAGS: "-mod=readonly"

stages:
  - verify
  - test
  - build
  - package

verify:
  stage: verify
  script:
    - make verify

test:
  stage: test
  script:
    - make test
  artifacts:
    reports:
      cobertura: coverage.txt

build_linux_amd64:
  stage: build
  script:
    - make linux_amd64 MODULES=all
    - make build_linux_amd64_image MODULES=all
  artifacts:
    paths:
      - target/chaosblade-*.tgz

```

The `GOFLAGS` variable ensures reproducible builds by preventing automatic module updates during CI execution.

## Running Chaos Experiments in CI

Beyond building the binary, you can validate that the compiled CLI functions correctly by executing a lightweight experiment during the pipeline:

```bash

# After make build or make linux_amd64 MODULES=all

./target/chaosblade-$(git describe --tags --abbrev=0)-linux_amd64/blade create cpu --cpu-percent 10 --timeout 5s

```

This command verifies that the experiment engine loads correctly and can access system resources. For automated testing, use the `--async` flag or wrap the command in a timeout to prevent hanging the CI runner.

## Artifact Publishing and Versioning

ChaosBlade derives its version string from Git tags via [`scripts/version.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/scripts/version.sh), which the Makefile invokes to set `BLADE_VERSION`. When `make package` runs in CI, it produces `chaosblade-${BLADE_VERSION}-linux-amd64.tar.gz` (and similar for other platforms).

To publish Docker images:

```bash

# Tag with registry destination

docker tag ghcr.io/chaosblade-io/chaosblade-tool:${BLADE_VERSION} \
  my-registry.com/chaosblade:${BLADE_VERSION}

docker push my-registry.com/chaosblade:${BLADE_VERSION}

```

The `make push_image` target can automate this step if `DOCKER_REGISTRY` and `DOCKER_USERNAME` environment variables are configured in your CI secrets.

## Summary

- **ChaosBlade** provides a **Makefile**-driven build system that standardizes compilation, testing, and packaging across all platforms.
- The **GitHub Actions** workflow in [`.github/workflows/ci.yml`](https://github.com/chaosblade-io/chaosblade/blob/main/.github/workflows/ci.yml) serves as the canonical reference for CI integration, using targets like `make verify`, `make test`, and `make build_linux_amd64_image`.
- **Jenkins** and **GitLab CI** can replicate the entire pipeline by calling the same Makefile targets, ensuring consistent behavior regardless of CI provider.
- Version management is handled automatically by [`scripts/version.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/scripts/version.sh), which extracts the `BLADE_VERSION` from Git metadata for reproducible artifact naming.
- Docker images built via `make build_linux_amd64_image` bundle the CLI and all experiment executors, creating a portable chaos engineering toolkit ready for deployment.

## Frequently Asked Questions

### Can I run ChaosBlade experiments directly inside CI pipelines?

Yes. After building the binary with `make build` or `make linux_amd64`, you can invoke `./target/.../blade create` to execute experiments. Use short timeouts (e.g., `--timeout 30s`) and low-intensity parameters (e.g., `--cpu-percent 10`) to validate the binary without destabilizing the CI runner itself.

### What Go version is required to build ChaosBlade?

The upstream CI workflow specifies **Go 1.25** (defined by the `GO_VERSION` environment variable in [`.github/workflows/ci.yml`](https://github.com/chaosblade-io/chaosblade/blob/main/.github/workflows/ci.yml)). The `Makefile` and `go.mod` files in the repository are maintained for compatibility with this version, though newer Go releases typically work without modification.

### How do I customize the build for specific platforms only?

Modify the `MODULES` variable when calling cross-compilation targets. For example, `make linux_amd64 MODULES=os,docker` builds only the OS and Docker experiment executors, reducing binary size and build time compared to `MODULES=all`. This is useful when you only target specific chaos engineering scenarios in your environment.

### Where does the version string come from in CI builds?

The version is derived by [`scripts/version.sh`](https://github.com/chaosblade-io/chaosblade/blob/main/scripts/version.sh), which inspects Git tags (using `git describe --tags --abbrev=0`) or falls back to the `BLADE_VERSION` environment variable. The Makefile then injects this value during compilation via `-ldflags`, ensuring that `./blade version` reports the correct semantic version in the resulting binary.