Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chainguard-dev/melange/llms.txt

Use this file to discover all available pages before exploring further.

melange is an open-source tool from Chainguard that lets you build APK packages entirely from declarative YAML configuration files. Instead of writing ad-hoc shell scripts or wrestling with traditional package-manager build phases, you define every step of your build as an ordered pipeline — and melange handles the rest, including environment setup, source fetching, compilation, and package assembly. The majority of packages built with melange target either the Wolfi or Alpine Linux ecosystems.

​
Why melange?

Secure software factories are the evolution of DevOps. By capturing compiled software artifacts as versioned, signed APK packages, teams gain the same auditability and reproducibility for their build outputs as they do for any other infrastructure component. melange is designed from the ground up to support this model. Two properties define the melange approach:
  • Pipeline-oriented builds. Every step of the build pipeline is defined and controlled by you, unlike traditional package managers which impose distinct, opaque phases. You compose reusable pipeline steps — called uses — or write inline runs commands, giving you full visibility into what happens at each stage.
  • Multi-architecture by default. melange uses QEMU user-mode emulation via binfmt_misc to build for foreign architectures without requiring cross-compilation toolchains. An x86_64 host can produce aarch64, armv7, riscv64, and other packages out of the box.

​
The Alpine/Wolfi ecosystem

APK is the package format used by Alpine Linux and Wolfi, a Linux distribution maintained by Chainguard that is specifically designed for container workloads. melange produces .apk files and signed APKINDEX repository indexes that are fully compatible with both ecosystems. melange is most commonly paired with apko, Chainguard’s tool for assembling OCI container images directly from APK packages. The typical workflow is:
  1. Use melange to build and package your application as an APK.
  2. Use apko to compose a minimal, hardened container image that installs that APK.
This pairing allows a single YAML-driven pipeline to take you from source code all the way to a production container image, with every artifact signed and attested along the way.

​
Key features

Pipeline-oriented builds

Define every build step explicitly in YAML. Compose reusable built-in pipelines (autoconf, go/build, cmake, and more) or write your own inline shell commands.

Multi-arch support

Build for x86_64, aarch64, armv7, ppc64le, riscv64, and other targets from a single host using QEMU emulation — no cross-compilation required.

Package signing

Sign your APKs and repository index with RSA keys generated by melange keygen. Signed packages can be verified by any standard APK client.

SLSA provenance

Pass --generate-provenance to emit SLSA provenance attestations alongside your packages, enabling downstream consumers to verify the build chain.

SBOM generation

melange generates Software Bill of Materials (SBOM) data for every package it builds, giving you a complete inventory of dependencies and licenses.

Linting and testing

Built-in linters catch common packaging mistakes (world-writable files, missing stripping, incorrect permissions) before a package is published. Package-level test pipelines let you validate behavior at build time.

​
Security model

melange builds run inside an isolated guest environment constructed by bubblewrap. The build guest is assembled from APK packages listed in environment.contents, ensuring that no host toolchain bleeds into the build and that the full dependency graph is explicit and auditable. Key security properties:
  • Reproducible environments. The build environment is assembled fresh from pinned APK packages for every build, eliminating implicit host dependencies.
  • Signed packages. RSA signing via melange keygen and --signing-key ensures that published packages can be verified by APK clients.
  • SLSA provenance. When --generate-provenance is passed, melange emits a .attest.tar.gz file alongside each APK containing SLSA provenance metadata.
  • Explicit licensing. The copyright block in every package configuration requires license and copyright information to be declared, and melange license-check can validate it.

​
Relationship with apko

While melange builds APK packages, apko assembles OCI container images from those packages. They are complementary tools that share the same YAML-driven, declarative philosophy. A common pattern is to keep both a melange.yaml and an apko.yaml in the same repository, building the package first with melange and then composing the image with apko using a local package repository: 
# 1. Build the package
melange build melange.yaml --signing-key melange.rsa

# 2. Build the container image using the local packages/ directory
apko build apko.yaml my-app:latest my-app.tar
For a working end-to-end example of a melange + apko workflow, see the nginx-image-demo repository on GitHub.

​
Explore the documentation

Quickstart

Build the GNU Hello package from scratch in under five minutes.

Installation

Install melange via Homebrew, Go, Docker, or from source.

Build file reference

Full reference for every field in a melange YAML configuration file.

Command reference

Complete CLI reference for all melange subcommands.

Build docs developers (and LLMs) love

Get started for freeTalk to us