Building container images

Image builds produce OCI artifacts and push them to the registry you configure. Clients pull those images—or through an optional read-only OCI proxy—and verify signatures and attestations according to your policy.

Registry and addressing

The worker pushes to an external OCI registry using registry_image_prefix plus registry credentials. You choose the registry (cloud or self-hosted); SecureBuild does not embed a registry server. For vanity URLs and stable pull hostnames, you can deploy the oci-proxy in front of the same registry; see Infrastructure and the configuration reference.

Dependency on packages

Images often install software from your APK repository (packages built by SecureBuild). Configure the APK repository URL and signing key for the UI and workers so installs resolve correctly; see Packages and How It Works for the relationship between Melange (packages) and image definitions.

Image (apko)

Example contents block for a development-oriented image that installs the go toolchain and busybox (and related tools) from the same APK origin (see Building overview for repositories / keyring):

contents:
  repositories:
    - https://apk.cve0.io
  keyring:
    - https://apk.cve0.io/key/cve0-signing.rsa.pub
  packages:
    - go~1.25.8
    - build-base
    - make
    - pkgconf
    - bash
    - git
    - curl
    - ca-certificates-bundle
    - securebuild-baselayout
    - busybox

environment:
  PATH: /go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  GOLANG_VERSION: "1.25.8"
  GOTOOLCHAIN: local
  GOPATH: /go

paths:
  - path: /go
    type: directory
    permissions: 0o1777
  - path: /go/src
    type: directory
    permissions: 0o1777
  - path: /go/bin
    type: directory
    permissions: 0o1777
  - path: /usr/local/go
    type: symlink
    source: /usr/lib/go
    permissions: 0o755

cmd: /bin/bash

work-dir: /go

The go~1.25.8 line pins the go APK to a specific version published in the repository (the ~ constraint matches that package version in the index). That keeps the image on a known toolchain for reproducible builds, which also lets you tag the image with something like 1.25.8 so the OCI tag matches the Go version and consumers get a fixed, known toolchain.

Verification

Supply chain verification—image signing, SBOMs, and attestations—is covered in Supply Chain Security and Attestations.

Where builds run

build_backend and related settings control whether image builds run on the worker host or on remote builders. See Where builds run under Infrastructure.