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

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 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 and 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.
• 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, 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. 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:

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:

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:

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

# 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 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, 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). 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}