Pipelines are the heart of every melange build. A pipeline is an ordered list of build steps declared inside your melange YAML configuration file. Each step either executes a shell snippet directly or invokes a named, reusable pipeline by reference. Steps share a common workspace directory — the build directory where sources are unpacked and artifacts are assembled — so the output of one step is naturally available to the next.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.
Step types
Every entry in thepipeline: list is either a runs: step (inline shell) or a uses: step (named pipeline). Both types accept optional fields that control naming, inputs, environment variables, and conditional execution.
runs: — inline shell
Use runs: when you need to execute arbitrary shell commands directly. The value is a multi-line string interpreted by the build shell:
uses: — named pipeline
Use uses: to invoke a built-in or custom pipeline by its file-system path (without the .yaml extension). Named pipelines accept structured inputs through the with: block:
Pipeline step fields
Each step in thepipeline: list supports the following fields:
name
name
An optional human-readable label for the step, useful for log output and debugging.
runs
runs
An inline shell script. All commands run inside the build container with the workspace as the working directory.
uses
uses
The name of a pipeline to invoke, specified as a path relative to the pipelines directory (omitting
.yaml). For example uses: go/build maps to pkg/build/pipelines/go/build.yaml.with
with
A map of named inputs to pass to a
uses: pipeline. The accepted keys are defined by the pipeline’s inputs: schema.environment
environment
Additional environment variables scoped to this step only.
if
if
A conditional expression. When the expression evaluates to false the step is skipped entirely. Melange variable substitutions are supported inside the expression.
assertions
assertions
Used on sub-pipeline wrappers to require that at least a minimum number of nested steps execute. Useful when combined with
if: guards on sub-steps.Shared workspace
All steps in a pipeline share the same working directory. Melange places source files (fetched tarballs, git checkouts) into this directory, and each subsequent step can read or modify what was written before it. The special variable${{targets.destdir}} points to the staging area where files should be installed before they are packaged into the APK.
A complete example
The following example fromexamples/gnu-hello.yaml shows a typical autoconf-based build using built-in pipelines:
fetch step downloads and verifies the source tarball. The autoconf/* steps run the standard ./configure && make && make install sequence. Finally, strip removes debug symbols from the installed binaries to reduce APK size.
Conditional steps and sub-pipelines
Theif: field supports melange’s variable substitution syntax to gate steps on build conditions such as architecture. The conditional.yaml example demonstrates all supported conditional patterns:
The
if: expression is evaluated using Go’s expression engine. Supported operators include ==, !=, <, >, <=, and >=. Variable references use the ${{...}} syntax.Next steps
Built-in Pipelines
Browse the complete catalogue of built-in pipelines including fetch, strip, patch, and ecosystem-specific helpers.
Custom Pipelines
Learn how to write your own reusable pipeline YAML files and load them with
--pipeline-dir.Go Pipelines
Build Go projects with the
go/build and go/install pipelines.Cargo Pipeline
Compile Rust packages using the
cargo/build pipeline with auditable builds.