Local Docker infrastructure for testing Brik pipelines end-to-end: write brik.yml, push to GitLab or Gitea, watch the pipeline run on real CI platforms.

Brik needs real CI/CD platforms to validate its shared libraries and runtime. Briklab provides that infrastructure locally via Docker Compose -- no cloud accounts, no shared servers.

• One command to set up everything (init)
• GitLab CE + Runner for GitLab CI pipelines
• Gitea + Jenkins for Jenkins pipelines
• Nexus 3 CE for artifact publishing (npm, Maven, PyPI, NuGet, Docker, Cargo)
• k3d (K3s in Docker) + ArgoCD for Kubernetes and GitOps deploy E2E testing
• SSH target container for deploy E2E testing
• E2E pipeline testing with 28 automated scenarios on each platform
• Managed by a Bash CLI (scripts/briklab.sh)

For internal architecture details, see docs/architecture.md.

• Docker Desktop (24 GB RAM recommended)
• jq (brew install jq)
• k3d (lightweight K3s in Docker) -- see install docs
• argocd CLI -- see install docs

Add to /etc/hosts:

127.0.0.1  gitlab.briklab.test nexus.briklab.test
127.0.0.1  gitea.briklab.test jenkins.briklab.test
127.0.0.1  argocd.briklab.test ssh-target.briklab.test

Add to Docker Desktop (Settings > Docker Engine):

{
  "insecure-registries": [
    "nexus.briklab.test:8082"
  ]
}

./scripts/briklab.sh init

GitLab takes 3-5 minutes on first start. Jenkins builds a custom Docker image on first start. Nexus takes 2-3 minutes. The script waits automatically.

Default credentials are defined in .env. Modify them before the first init.

Setup creates 6 hosted repositories for artifact publishing:

Platform is required: --gitlab or --jenkins. All other flags are identical.

# Day 1 - Full setup
./scripts/briklab.sh init                    # First time setup (~5 min)
./scripts/briklab.sh test --gitlab --all     # Run GitLab E2E suite
./scripts/briklab.sh test --jenkins --all    # Run Jenkins E2E suite
./scripts/briklab.sh stop                    # Done for the day

# Day N
./scripts/briklab.sh start                   # Restart (fast, data preserved)
./scripts/briklab.sh test --gitlab           # Quick GitLab smoke test
./scripts/briklab.sh test --jenkins          # Quick Jenkins smoke test
./scripts/briklab.sh stop                    # Done

Each GitLab E2E scenario pushes a test project to briklab GitLab, triggers a pipeline, and validates that specific jobs pass.

node-deploy-dryrun reuses the node-deploy project with BRIK_DRY_RUN=true. node-deploy-rollback uses node-deploy-gitops-rollback with a 3-step commit chain: deploy v0.1.0, deploy v0.2.0, revert config repo to verify ArgoCD rolls back to v0.1.0 image.

Workflow scenarios run sequentially: workflow-trunk-main pushes to main, then workflow-trunk-tag creates a tag on the same project, then workflow-trunk-feature creates a feature branch. Each depends on the previous one.

Jenkins E2E testing mirrors the GitLab scenarios: pushes the Brik shared library and test projects to Gitea, then triggers Jenkins pipelines via the REST API.

The Jenkins pipeline runs the full Brik fixed flow:

Init -> Release -> Build -> Quality & Security -> Test -> Package -> Deploy -> Notify

Jenkins runs the same 28 scenarios as GitLab (minimal, full, complete, security, deploy, helm, workflow, error). The E2E framework supports CI variable injection via buildWithParameters.

# Run the default Jenkins E2E pipeline (node-minimal)
./scripts/briklab.sh test --jenkins

# Run the full Jenkins E2E suite
./scripts/briklab.sh test --jenkins --all

# Run a specific scenario
./scripts/briklab.sh test --jenkins --project node-deploy-k8s

# List available scenarios
./scripts/briklab.sh test --jenkins --list

Test project fixtures live in test-projects/. Each has a brik.yml and platform-specific CI config (.gitlab-ci.yml for GitLab, Jenkinsfile for Jenkins).

Runner images are selected automatically by the init job based on project.stack and project.stack_version in brik.yml. The init job resolves the image and propagates it via dotenv to downstream jobs. Images are published at ghcr.io/getbrik/brik-runner-<stack>:<version>.

Full suite run on 2026-04-18

GitLab won't start -- Check Docker Desktop has at least 18 GB RAM allocated. First start takes 3-5 minutes. Check logs: ./scripts/briklab.sh logs gitlab

Runner errors (runner_system_failure / image_pull_failure) -- Verify helper_image is present in the runner's config.toml. Check logs: ./scripts/briklab.sh logs runner. If needed, re-run ./scripts/briklab.sh setup.

Jenkins CasC errors -- Check ./scripts/briklab.sh logs jenkins for Configuration-as-Code errors. Common issue: plugin not installed. Verify images/jenkins/plugins.txt includes all required plugins. To reload CasC without restarting Jenkins, use the jenkins_reload_casc helper in briklab.sh (only works for CasC YAML changes; env var changes require a full restart).

Jenkins pipeline can't find Brik library -- The Brik shared library must be pushed to Gitea before triggering a pipeline. Run ./scripts/briklab.sh setup to ensure Gitea is configured, then push repos with the E2E test command.

Gitea shows install page -- On first start, Gitea requires initial installation. The setup script handles this automatically. If it fails, check logs: ./scripts/briklab.sh logs gitea

Nexus slow to start -- First start takes 2-3 minutes (JVM + plugin initialization). The healthcheck has a 180s start_period. Check logs: ./scripts/briklab.sh logs nexus

Nexus Docker push fails (HTTP) -- Add "nexus.briklab.test:8082" to insecure-registries in Docker Desktop settings. The Nexus Docker registry uses HTTP, not HTTPS.

Nexus repository creation fails -- If setup is run before Nexus is fully ready, repository creation may fail. Wait for the healthcheck to pass, then re-run: ./scripts/briklab.sh setup

k3d cluster already exists -- k3d cluster delete brik && ./scripts/briklab.sh k3d-start

ArgoCD won't sync -- ArgoCD default polling is ~3 minutes. Use argocd app get <app> --refresh hard to force, or run ./scripts/briklab.sh infra-refresh to renew port-forwards and tokens.

E2E timeout -- Use --batch-size 4 to limit concurrent pipelines. Check runner saturation with ./scripts/briklab.sh logs runner. Run ./scripts/briklab.sh infra-refresh if tokens expired.

Reset between E2E runs -- ./scripts/briklab.sh reset --gitlab cleans repos, k8s namespaces, ArgoCD apps, and Nexus artifacts.

For the complete list of known issues and solutions, see docs/architecture.md - Known Gotchas.

# Stop containers (data preserved)
./scripts/briklab.sh stop

# Delete all data and volumes (irreversible, requires confirmation)
./scripts/briklab.sh clean

# Delete k3d cluster
k3d cluster delete brik

# Full removal: after clean, remove Docker images manually
docker rmi gitlab/gitlab-ce:18.10.1-ce.0 gitlab/gitlab-runner:alpine3.21-bleeding
docker rmi gitea/gitea:1.25.5
docker rmi briklab-jenkins  # custom-built Jenkins image
docker rmi sonatype/nexus3:3.90.2-alpine
docker network rm brik-net 2>/dev/null

Briklab scripts are organized into reusable libraries under scripts/lib/:

scripts/
  briklab.sh                    # CLI entry point
  lib/
    common.sh                   # Shared utilities (logging, retry, env loading)
    infra-verify.sh             # Environment verification
    infra-refresh.sh            # Token/port-forward refresh
    auth/
      gitlab-pat.sh             # GitLab PAT management
      gitea-pat.sh              # Gitea PAT management
      argocd-token.sh           # ArgoCD token retrieval
      argocd-portfwd.sh         # ArgoCD port-forward management
    setup/
      gitlab.sh                 # GitLab CE configuration
      runner.sh                 # GitLab Runner registration
      gitea.sh                  # Gitea configuration
      jenkins.sh                # Jenkins CasC + Job DSL
      nexus.sh                  # Nexus repository creation
      k3d.sh                    # k3d cluster + ArgoCD install
      ssh-target.sh             # SSH target container setup
      smoke-test.sh             # Post-setup health checks
    e2e/
      gitlab-push.sh            # Push repos to GitLab
      gitlab-test.sh            # Single GitLab pipeline test
      gitlab-suite.sh           # GitLab scenario orchestrator
      gitlab-rollback.sh        # GitLab rollback E2E
      gitea-push.sh             # Push repos to Gitea
      jenkins-test.sh           # Single Jenkins pipeline test
      jenkins-suite.sh          # Jenkins scenario orchestrator
      jenkins-rollback.sh       # Jenkins rollback E2E
      lib/                      # Reusable E2E libraries (17 files)
        assert.sh               # Assertion framework
        auth.sh                 # PAT validation
        suite.sh                # Suite orchestrator (groups, batches)
        push.sh                 # Git push helpers
        git.sh                  # Git operations
        reset.sh                # State cleanup between runs
        rollback.sh             # Rollback test helpers
        gitlab-api.sh           # GitLab API client
        jenkins-api.sh          # Jenkins API client
        gitea-api.sh            # Gitea API client
        nexus.sh                # Nexus artifact verification
        k8s.sh                  # Kubernetes assertions
        argocd.sh               # ArgoCD sync/status
        compose.sh              # Docker Compose assertions
        ssh.sh                  # SSH deploy assertions
        error-patterns.conf     # Error detection patterns
        error-ignore-patterns.conf  # False positive filters

Auth libraries are reusable -- each validates and caches credentials, and can be sourced from any script.

• GitLab CE + Runner
• Gitea + Jenkins (CasC + Job DSL)
• Nexus 3 CE -- artifact publishing (npm, Maven, PyPI, NuGet, Docker, Cargo)
• Automated init with smoke tests
• E2E pipeline testing -- GitLab (28 scenarios: minimal, full, complete, security, deploy, helm, workflow, error)
• E2E pipeline testing -- Jenkins (28 scenarios, same coverage as GitLab)
• Security stage E2E
• Deploy stage E2E (k8s, ssh, compose, gitops, helm, rollback, failure)
• CI variable injection for E2E scenarios (dry-run, rollback tests)
• SSH target container for deploy E2E
• Error scenario E2E (build fail, test fail, invalid config, deploy fail)
• k3d + ArgoCD integration (setup script, CLI commands, gitops E2E scenario)
• Script refactoring into reusable libraries (auth, setup, e2e)
• Helm deploy E2E (k3d)
• Workflow trunk-based E2E (main, tag, feature branch)
• E2E framework with 17 reusable libraries
• Parallel groups and batch execution (--groups, --batch-size)
• State reset between runs (reset command)
• Infrastructure refresh (infra-refresh command)

• Brik -- the portable CI/CD pipeline system
• Architecture -- how Briklab works internally

We use AI-assisted development (Claude Code + Everything Claude Code) to accelerate implementation:

• Every contribution (human or AI-generated) follows the same quality gates: code review, test coverage, E2E testing, and CI checks.
• AI-generated code is not perfect. Regular refactoring passes address its shortcomings, and the overall productivity gains are significant.

MPL-2.0