Skip to content
BranchesTags

Repository files navigation

gomnibus

A Go-based rewrite of Chef Omnibus — build full-stack, self-contained software installers from declarative YAML definitions.

CI Kitchen codecov Go Report Card Go version Release License

gomnibus produces cross-platform packages (.deb, .rpm, .pkg, .msi, .tar.gz) that embed an application together with all its runtime dependencies. No system Ruby, no Bundler, no Gemfile — just a single Go binary and YAML definitions.

Features

  • Declarative YAML DSL for project and software definitions
  • Multiple fetcher backends: HTTP(S) with checksum verification, Git (branch/tag/commit), local path, S3
  • All major build systems: ./configure, CMake, Make, Go, Gem, and arbitrary shell commands
  • Dependency-ordered builds via topological sort with cycle detection
  • Parallel builds: configurable worker count; nodes become eligible the instant all their dependencies finish — maximum DAG parallelism
  • Build caching: local content-addressable cache, S3 remote cache, or both via ChainCache (local-first, remote fallback)
  • Package formats: .deb (dpkg-deb), .rpm (rpmbuild), .pkg (pkgbuild + productbuild), .msi (WiX v3/v4), .tar.gz universal
  • Test Kitchen integration: gomnibus kitchen test|create|converge|verify|destroy|list|login with Docker and Vagrant drivers
  • Shared-library health check (ldd/otool) with per-software whitelist
  • Version manifest (JSON) for reproducible builds
  • License collection and compliance checking
  • Version overrides in project files — pin any dependency to a specific version
  • Multi-version software definitions — conditional source/build per version

Installation

go install github.com/syntaxroot-cc/gomnibus/cmd/gomnibus@latest

Or build from source:

git clone https://github.com/syntaxroot-cc/gomnibus
cd gomnibus
git submodule update --init          # pulls lib/gomnibus-software
go build ./cmd/gomnibus

Quick start

# Create a new project skeleton
gomnibus new myapp

# Edit the generated files
vim config/projects/myapp.yaml
vim config/software/myapp-software.yaml

# Validate without building
gomnibus validate myapp

# Build and package
gomnibus build myapp

# Print the version manifest
gomnibus manifest myapp

Project layout

gomnibus.yaml                  # global config
config/
  projects/
    myapp.yaml                 # project definition
  software/
    zlib.yaml                  # software component definitions
    openssl.yaml
    myapp.yaml
pkg/                           # output packages

Software definition

config/software/openssl.yaml:

name: openssl
default_version: "3.3.1"
license: OpenSSL

source:
  url: "https://www.openssl.org/source/openssl-3.3.1.tar.gz"
  sha256: "777cd596284c883375a2a7a11bf5d2786fc5413255efab20c50d6ffe6d020b7e"

relative_path: "openssl-3.3.1"
dependencies:
  - zlib

build:
  - configure:
      - "--disable-option-checking"
      - "--with-zlib=${install_dir}"
  - make: []
  - make:
      - install

Variables ${install_dir}, ${src_dir}, and ${build_dir} expand in all step types including configure:, make:, cmake:, go:, and gem: arg lists. The configure: step automatically prepends --prefix=${install_dir} — do not include it manually.

Project definition

config/projects/myapp.yaml:

name: myapp
maintainer: "Acme <packages@acme.com>"
homepage: "https://acme.com"
description: "Acme application with all dependencies bundled"
install_dir: /opt/myapp
build_version: "2.1.0"
build_iteration: 1
dependencies:
  - zlib
  - openssl
  - myapp
overrides:
  - name: openssl
    version: "3.3.1"
packages:
  - type: deb    # Linux (Debian/Ubuntu)
  - type: rpm    # Linux (RHEL/Rocky/Fedora)
  - type: pkg    # macOS — requires Xcode Command Line Tools
  - type: msi    # Windows — requires WiX v4 (dotnet tool install -g wix) or WiX v3
  - type: tar    # universal fallback

Global configuration

gomnibus.yaml (generated by gomnibus new, all fields optional):

# Build cache
use_git_caching: true          # local content-addressable cache (default: true)
use_s3_caching: false          # S3 remote cache (default: false)
s3_bucket: ""                  # required when use_s3_caching: true
s3_region: "us-east-1"
s3_prefix: "gomnibus/cache"    # key prefix in the bucket
s3_access_key: ""              # leave empty to use instance profile / env vars
s3_secret_key: ""
s3_profile: ""                 # AWS credentials profile name
s3_iam_role_arn: ""            # assume-role ARN for cross-account access

# Build settings
workers: 4                     # parallel build workers (default: 4)
append_timestamp: false        # append build timestamp to package names
log_level: info                # debug | info | warn | error

# Software search path (first-found wins; project-local before shared library)
software_dirs:
  - config/software
  - lib/gomnibus-software/config/software

When both use_git_caching and use_s3_caching are true, gomnibus uses a ChainCache: local hit → return immediately; local miss → check S3 → backfill local on hit; miss → build and store to both.

CLI reference

gomnibus new PROJECT            Generate project skeleton
gomnibus build PROJECT          Fetch, build, and package
gomnibus manifest PROJECT       Print JSON version manifest
gomnibus validate PROJECT       Validate definitions (no build)
gomnibus changelog              Generate CHANGELOG from git history

gomnibus kitchen list           List platforms and their state
gomnibus kitchen test [REGEX]   Create → converge → verify → destroy
gomnibus kitchen create [REGEX] Spin up instances
gomnibus kitchen converge [REGEX]  Run the build inside instances
gomnibus kitchen verify [REGEX] Run verifiers against instances
gomnibus kitchen destroy [REGEX]  Tear down instances
gomnibus kitchen login INSTANCE  Open a shell in an instance

Global flags:
  -c, --config string           Config file (default: gomnibus.yaml)
  -l, --log-level string        debug | info | warn | error (default: info)
  -o, --output string           Output directory for packages (default: pkg)
  -p, --package-type string     Override package type (deb, rpm, pkg, msi, tar)
      --skip-healthcheck        Skip shared-library health check

Kitchen flags:
  -K, --kitchen-config string   Kitchen config file (default: .kitchen.yml)
      --concurrency int         Parallel instances (default: 1)
      --output string           Package output directory (default: pkg/kitchen)

Test Kitchen

gomnibus ships a built-in Test Kitchen runner for multi-platform integration testing. Place a .kitchen.yml in your project root:

driver:
  name: docker

provisioner:
  name: gomnibus
  project: myapp
  gomnibus_binary: /usr/local/bin/gomnibus

verifier:
  name: shell

platforms:
  - name: ubuntu-22.04
    driver:
      image: ubuntu:22.04
    verifier:
      command: dpkg -l | grep myapp

  - name: rockylinux-9
    driver:
      image: rockylinux:9
    provisioner:
      install_packages: [gcc, make, perl, rpm-build, git, curl]
    verifier:
      command: rpm -q myapp

suites:
  - name: default

Then run:

gomnibus kitchen test           # all platforms
gomnibus kitchen test ubuntu    # filter by name

gomnibus-software library

syntaxroot-cc/gomnibus-software is a curated library of reusable software definitions (zlib, OpenSSL, curl, libffi, and more), included as a git submodule at lib/gomnibus-software.

After cloning:

git submodule update --init

Reference in gomnibus.yaml:

software_dirs:
  - config/software                               # project-local (takes precedence)
  - lib/gomnibus-software/config/software         # shared library

Comparison with Ruby Omnibus

Feature Ruby Omnibus gomnibus
Definition language Ruby DSL YAML
CLI tool omnibus gomnibus
Single binary No (requires Ruby) Yes
Fetchers url, git, path, s3 url, git, path, s3
Build systems make, configure, rake... make, configure, cmake, go, gem...
Dep ordering ✓ ✓
Parallel builds limited ✓ (DAG-aware, configurable workers)
Version overrides ✓ ✓
Multi-version blocks ✓ ✓
Health check ✓ ✓
Version manifest ✓ ✓
License collection ✓ ✓
.deb / .rpm packaging ✓ ✓
.pkg (macOS) ✓ ✓ (pkgbuild + productbuild)
.msi (Windows) ✓ ✓ (WiX v3/v4, auto-detected)
.tar.gz universal ✓ ✓
Local build cache ✓ (git-based) ✓ (content-addressable)
S3 remote cache ✓ ✓ (ChainCache: local-first + S3)
Test Kitchen integration ✓ ✓ (Docker + Vagrant drivers)

Contributing

See CONTRIBUTING.md for dev setup, the git hooks, and code conventions. After cloning, enable the pre-commit hook with:

git config core.hooksPath .githooks

The Claude Code configuration in .claude/ contains agents, skills, and prompts to help implement new features.

License

Apache License 2.0 — see LICENSE.

About

A Go-based full-stack installer build system — a complete rewrite of Chef Omnibus in Go. Build self-contained, cross-platform packages (.deb, .rpm, .pkg, .msi) with a declarative YAML/HCL DSL.

github.com/syntaxroot-cc/gomnibus

Topics

build-toolclicross-platformdebdevopsgogolanginstallermsiomnibuspackagingpkgrpm

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages