Contributing to wolfi-dev/os

August 5, 2026 ยท View on GitHub

How this repository works

wolfi-dev/os is a read-only public clone of the core Wolfi OS. As described in the organization overview, it is a sync from internal Chainguard repositories. Proposed improvements are applied internally and then synced back out to this public repository.

As a result:

  • Pull requests opened here cannot be merged directly.
  • Changes are shepherded by a Chainguard engineer on a best-effort basis.
  • Acceptance and timelines are not guaranteed.

If you are a Chainguard customer, please contact your Customer Success representative for additional support.

Package inclusion and removal

Which packages exist in Wolfi is governed by Chainguard. Wolfi provides the packages required to build or run free Chainguard Containers. Package definitions are regularly added and removed as upstreams and images change. See the FAQ in the organization overview for the current package inclusion, retention, and removal policy.

Building and testing packages locally

You can build and test Wolfi packages locally, for example to reproduce a build, validate a proposed change, or scan a package for vulnerabilities.

Setup development environment

To ease the development of Wolfi OS, you can use the Wolfi sdk image that already includes both apko and melange. On Linux and Mac it is also possible to install both the above tools directly into your system.

If you choose not to install the tooling onto your local machine, you can start a container based development environment using

make dev-container

What it does is start the ghcr.io/wolfi-dev/sdk image and mount the current working directory into it.

Building a package

Wolfi packages are built using melange. If you want to learn how packages are built, you can see all the details in the Makefile.

To build an individual package, you can use a make command like this:

make package/<package-name>

For example, if the package name is "foo", run make package/foo.

This will build the package by invoking melange in a particular way. This invocation is defined in the Makefile, if you're interested to see how this is wired up. Also, you can run Melange directly without using make if you understand what you're doing.

Note: The build system has a cache of source files that may help reduce the time your build takes. Feel free to see if this cache helps you by adding USE_CACHE=yes to the command above. If you encounter issues with this approach, the best advice is to remove the USE_CACHE=no from your command and carry on with your builds.

When the build finishes, your package(s) should be found in the generated ./packages directory.

Scanning a package for vulnerabilities

You can scan a package you built for vulnerabilities, using wolfictl's scan command:

wolfictl scan ./packages/some-architecture/your-package-name-and-version.apk

Check for anything unexpected, or for any CVEs you can patch.

Package versioning

  • When bumping the version of a package, you will need to update the version, epoch & shasum (sha256 or sha512) in the package YAML file. The version and epoch also need to be bumped in Makefile.

  • epoch needs to be bumped when the package version remains the same but something else changes. epoch needs to be reset to 0 when it's a new version of the package.

  • melange CLI has a command bump to make it easier. More details are available here.

Some tips

  • melange has a few built-in pipelines. You can see their source code in the melange repository.

  • You don't need to add environment.contents.repositories and environment.contents.keyring. Those are added automatically.

  • For patching CVEs, you can follow the documentation here.

  • When deciding how to add update: configuration see the update docs

  • Make sure your YAML file(s) are formatted correctly, so that they'll pass CI. We use yam for YAML formatting. You should be able to run the yam command from the root of this repo to get all files formatted correctly.

  • When running a lot of melange builds using docker as a runner (default on Mac) you may want to increase the Docker VM CPU, Memory and especially storage resources, else Docker can easily run out of disk space.