Container images are one of the basic building blocks of modern software development. When a developer makes a change to their code, the application is packaged into an image and pushed out into the world for delivery and deployment via a CI pipeline. With teams striving towards deployment automation in the context of CI/CD practices, image updates likely occur multiple times a week or sometimes even in a day. Over time, teams accumulate a growing amount of images and image versions that can easily become impractical to manage. What if you need to find a specific image version that introduced a bug? Or roll back to a version from a previous deployment? Digging through hundreds of builds can be a tedious task even when applying version and tagging best practices.

An Internal Developer Platform built with Humanitec allows teams to manage the orchestration of their container images. Once a new image build reaches the platform, its journey might continue in various ways: It might initiate an automated deployment to an environment, be used to create a new container in a workload or be rolled back to for example.

We’ve been working on providing a more convenient way for our users to manage images at scale and are happy to announce the release of several upgraded image management capabilities.

A new way to manage images in Humanitec

Managing container images and their versions has never been easier! We introduced a new set of features that rely on the artefact API, as part of which the following properties have been overworked:

  • Images are no longer referenced via a unique Humanitec ID. Instead, the image name serves as the main identifier. For example
  • Image sources, which allowed grouping versions of images together via the ID have been removed. Image builds can now be grouped by repository.
  • The image payload has been simplified. Image branch and tag can now be defined via the ref field. For example refs/heads/main or refs/tags/1.4.2.

Check out the artefact API documentation to have a look yourself and explore its capabilities - which are now available in the UI as well. The image section on Workload Details Screen in particular has undergone a notable design change:

It is now possible to:

Provide an optional image digest for new image versions

Image digests are collision resistant hashes of container images. While tags are mutable, digests provide an alternative way of uniquely identifying a container image and verifying it is the desired image. As part of a good DevSecOps process, it is common practice to pull images by digest. It helps to prevent attacks or accidents where an image tag is overwritten.

Change the image on a container

Developers can swap out the image of an already existing container by clicking on the Change image button. This functionality has been available via the API priorly and is made available in the UI as part of the release.

Manage image versions at scale

Image versions are managed via an overlay that appears when clicking on the Change version button. You’ll be able to filter for versions, commits or references, making it easy to track down a specific build. Additionally did we add support for:

  • Archiving & Unarchiving: As images get added to Humanitec, the list of possible image versions gets very long. This makes it impractical to manage. In most cases, older image versions are no longer needed. Archiving an image version means that it will no longer appear by default and can be restored any time.
  • Disabling Overridden Image Versions: When working with image tags, only the latest available version under a given tag can be selected and deployed by the user. Previous versions are overridden whenever a new image version is pushed under the same tag. If a version has been overridden, it is marked as such in the UI and treated as archived.

Another update has been made to the Organization Settings Screen, which allows teams to manage images registered with Humanitec.

How will current users of Humanitec be affected by this release?

The newly introduced artefact API is backwards compatible and does not introduce any breaking changes. Its predecessor, the image API has been marked as deprecated. This means it is no longer recommended for use, even though it is still operational. We’re planning to finally remove support for it in Spring of 2023.

If you are using Humanitec’s out-of-the-box CI pipeline integration for GitHub Actions, no further actions have to be taken on your end. In all other cases, a small update to your CI pipeline is required: The request in the code snippet that notifies Humanitec about new image builds needs to be made to the new artefact version POST endpoint:${orgID}/artefact-versions. The updated code snippet can be copied from your organization settings as described in the Notify Humanitec guide.

If you have any questions or run into a problem, please contact our support team directly.