TheDocumentation 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.
environment: section of a melange build file controls everything about the sandbox in which your package is compiled. It determines which APK repositories are searched, which signing keys validate those repositories, which packages are installed as build-time dependencies, which user runs the build, and which environment variables are set before any pipeline step executes. Getting the environment right is the first step to a reproducible, hermetic build.
The
environment block can only be specified at the top-level of the build configuration. Subpackage build definitions inherit it automatically and cannot override it. Subpackage test definitions are the exception — they may declare their own environment.contents
The contents sub-section defines the three ingredients of the build environment’s package layer: repositories to fetch from, keys that authenticate those repositories, and the specific packages to install.
repositories
A list of APK repository URLs. melange installs packages exclusively from these sources. Do not mix Alpine and Wolfi repositories in the same build — they use incompatible package sets.
Wolfi OS
Alpine Edge
keyring
A list of public-key URLs used to verify repository signatures. Every repository you add should have a corresponding keyring entry.
packages
The list of APK packages to install into the build environment. These are the build-time dependencies — tools and libraries needed to compile the package but not necessarily present at runtime. Runtime dependencies belong in package.dependencies.runtime.
Build environment vs. runtime dependencies
It is important to distinguish between the two kinds of dependencies in a melange build file:| Where declared | When used | Example |
|---|---|---|
environment.contents.packages | During the build pipeline only | gcc, make, go, cmake |
package.dependencies.runtime | After the package is installed by a user | openssl, ca-certificates-bundle |
environment.contents.packages are present inside the build sandbox. Packages listed under package.dependencies.runtime are recorded in the APK metadata but are not available during the build itself.
environment (environment variables)
The nested environment.environment map sets shell environment variables that are exported for every pipeline step. This is where you configure build flags, tool paths, and cross-compilation settings.
accounts
The accounts sub-section lets you create users and groups inside the build environment and optionally run the build as a specific user.
run-as
Specifies which user should execute the build pipeline. The user must already exist or be declared in the users list. The default build user is build. Specifying root is sometimes necessary when the build requires privileged operations such as making a binary setuid.
users and groups
Inject custom users and groups into the build image. Each user entry requires a username, uid, and gid. Each group entry requires a groupname and gid.
Workspace and guest directories
When melange runs a build it establishes two key locations inside the sandbox:- Guest directory — the root filesystem of the build environment, populated with the packages listed in
environment.contents.packages. - Workspace directory (
/home/build) — the working directory for the build. Source archives are extracted here and pipeline commands are executed from here. This path is available via the${{package.srcdir}}substitution.
/home/build/melange-out/. The substitutions ${{targets.destdir}} and ${{targets.subpkgdir}} point into this directory for the main package and subpackages respectively.
Full environment example
The following snippet shows a completeenvironment block for a Go package built against Wolfi, with CGO disabled and a pinned Go version: