Pinning Package Versions in Custom Assembly with chainctl

What this covers

How to have Custom Assembly use a specific package version in a custom image using chainctl, instead of always taking the latest package.

1. Core idea

In the Console UI, Custom Assembly always shows and uses the latest supported version for each package in a given version stream; you cannot select arbitrary older builds there. By design, we only maintain the latest version of packages: we don’t recommend pinning old versions in Chainguard images because they will accumulate CVEs over time and we won’t backport all fixes into those older builds. Our model is to keep customers on supported, up‑to‑date versions rather than hold them on a specific one.

Using chainctl to pin an exact package version is therefore an advanced, exception‑only workflow to manage compatibility risk and possible break changes. It trades off some of the automatic security benefits for more control over when you adopt upstream changes.

2. Exact version pin: pkg=VERSION

1. Edit the Custom Assembly config for a repo:

chainctl images repos build edit \
  --parent $ORGANIZATION \
  --repo $REPO \
  [--save-as $NEW_REPO]

2. In the editor, set contents.packages like:

contents:
  packages:
    - gettext=0.26-r0   # exact pin
    - curl              # latest compatible

• This syntax (gettext=0.26-r0) is confirmed to work in production conversations and is the recommended way to lock a specific package version via chainctl.

3. Save and confirm when chainctl shows the diff.

Use --save-as $NEW_REPO if you don’t want to change the behavior of the existing repo for other teams (e.g. create python-custom instead of modifying python).

3. Version stream pin: pkg~MAJOR / pkg~MAJOR.MINOR

If you want to stay on a major/minor stream but still pick up security updates in that stream:

contents:
  packages:
    - bash~5      # any 5.x
    - bash~5.2    # any 5.2.x

Engineering has validated that this apk fuzzy syntax works when set via chainctl images repos build edit/apply:

• bash~5 selects a 5.x version.
• bash~5.2 selects a 5.2.x version.

This is a highly recommended approach, as it will not lock to a major/minor version but will still receive patch updates.

4. How to find versions

4.1 chainctl packages versions list (for main/version-streamed packages)

For main/version-streamed packages (like python, tomcat, etc.):

chainctl packages versions list python --show-eol

This shows version streams and EOL dates and can help pick a major/minor stream to target.

If you see:

Error: [NotFound] no versions found for <pkg>

that just means there’s no version-stream metadata for that package name (common for many leaf APK packages like gcc, gettext, etc.), not that the package doesn’t exist.

4.2 apk search (works for any APK package)

From any Chainguard image with apk configured:

apk update
apk search -v gettext

Pick the desired name-VERSION-rN string (e.g. gettext-0.22.5-r3) and use that VERSION-rN in your contents.packages entry:

contents:
  packages:
    - gettext=0.22.5-r3

5. Short guidance

• Yes, it is possible to pin package versions in Custom Assembly when using chainctl.
• Use contents.packages entries with:
  • Exact pin: pkg=VERSION
  • Stream pin: pkg~MAJOR or pkg~MAJOR.MINOR
• Discover versions via apk search -v pkg (always works) or chainctl packages versions list (for main/version-streamed packages).
• Note that:
  • The old pinned versions will stop getting security updates.
  • Builds can fail if pinned versions conflict with other dependencies or are removed from active maintenance. The build failures will be visible on the console output.
  • It’s highly recommended to use fuzzy matching like ~ instead of pinned =.