recipe.yml

A recipe.yml file describes the build process of a custom image. One recipe file corresponds to one published image. Every recipe file specifies the full metadata, base image, and build process of a custom image.

Tip

This is the reference page for Recipe V2. If you’re still on V1, see the Recipe V1 reference page. Don’t know what this means? Read the blog post: Introducing Recipe V2

Tip

You can add the lines below to the top of your recipe to get yaml completion in your favorite editor.

# yaml-language-server: $schema=https://schema.blue-build.org/recipe-v2.json

Reference

version: (required)

2

The version of the recipe file schema.

base:

object

Options for the base image like the image and public key.

image:

unknown

The base image ref.

public-key:

string

The public key used to verify the base image signature. This will validate the image before building with it.

URLs are supported. Paths are relative to the root of the project.

metadata:

object

Metadata for the image like the name, description, and labels.

name:

string

The image name. Used when publishing to GHCR as ghcr.io/user/name.

description:

string

The image description. Published to GHCR in the image metadata.

labels:

object

A collection of custom labels that will be applied to the image.

Each item should be a key: value pair representing a label name mapping to label value.

spec:

object

Specifications for the image that modifies how it is built and published.

tags[]:

array of string

Allows setting custom tags on the recipe’s final image. Adding tags to this property will override the latest and timestamp tags.

platforms[]:

array of enum with valid values:

• linux/amd64
• linux/amd64/v2
• linux/arm64
• linux/arm
• linux/arm/v6
• linux/arm/v7
• linux/386
• linux/loong64
• linux/mips
• linux/mipsle
• linux/mips64
• linux/mips64le
• linux/ppc64
• linux/ppc64le
• linux/riscv64
• linux/s390x

Specify a list of the platforms to build for your image. The resulting images will be added to a manifest list that allows your host’s container runtime to pull the correct image architecture for your hardware. The process of building a multi-architecture image will end up using emulation. Consequently, image builds will take significantly longer and more space will be required on the build host since each platform that is being built is its own image. If platforms: is not specified, the build host’s architecture will be used.

tool-versions:

object

Extra tooling version overrides.

bluebuild:

string

The tag to pull for the BlueBuild cli. This is mostly used for trying out specific versions of the cli without compiling it locally. Supply the tag of the cli release container to pull, see the list of available tags for reference. Default: latest-installer. Set to to none to opt out of installing the CLI into your image.

cosign:

string

The version of cosign that will be included in the image. This will override the default version set by the CLI. Setting to none will prevent installing cosign altogether.

nushell:

string

The version of nushell to include at /usr/libexec/bluebuild/nu/nu for use by modules in the image. This will override the default BlueBuild Nushell version. Change only if you need a specific version of Nushell, changing this might break some BlueBuild modules.

stages[]:

array of enum with valid values:

• external

• external

A list of stages that are executed before the build of the final image. This is useful for compiling programs from source without polluting the final bootable image.

modules[]: (required)

array of enum with valid values:

• external

• external

A list of modules that is executed in order. Multiple of the same module can be included.

Each item in this list needs have at least a type: except if the configuration is included from an external file in the recipes/ directory with from-file:.

Example:

modules:
 - from-file: common-packages.yml # an external module configuration file for installing commong packages
 - type: signing # a module that doesn't require any configuration