Container registry

Our internal container registry based on open source Harbor project (a private, Docker-Hub–like service) hosts OCI container images for use on University compute facilities (e.g., HPC and Condor clusters). OCI (Open Container Initiative) is the open standard for container images, runtimes, and distribution, ensuring compatibility across tools like Docker and enabling Apptainer to pull/convert OCI images.

Images published to the registry are publicly readable within the University. This means anyone on the network can pull them.

Note

The registry is not available on the internet, it is only accessible from the University network or via VPN.

Viewing the registry

The registry has a web UI that can be used for browsing the images currently published there. You will need to log in with your University of Surrey credentials.

URL: https://container-registry.surrey.ac.uk

This is useful for discovering available images and verifying your own pushes/tags.

Image retention policies

In the interest of being efficient with disk space, there are weekly garbage collection (GC) processes running on the registry. This means that the registry will remove old and redundant images.

Garbage collection (image deletion) is based on the following policies:

Tag state

Deleted by GC?

Notes

‘latest’

no

Reserved for your current “most recent” version. only one image can have this tag at the time

any custom tag

no

Use for important or stable versions

only a “SHA_*******” tag applied

yes

Default tag from CI pipeline; not for long-term retention

no tags applied

yes

Untagged images are considered redundant and removed by GC

Note

the “SHA_*******” tag is a default tag applied by the GitLab CI pipeline when publishing images to the registry it can be used for referencing when you want to test an image but should not be used longer term.

If you need an image to persist, always apply at least one custom tag (e.g., v1.3.0, 2025-08-17, experiment-a), and optionally keep latest pointing to your most current build.

For help with tagging conventions, see Tagging container images

Caution

Registry storage is monitored. If your images consume excessive space, IT Services may ask you to remove unused images/tags. Proactively clean up obsolete tags and builds to avoid interruptions.

Tagging container images

Tags are mutable named references to specific versions of container images. There are many reasons and benefits for using tagging. This article has a pretty good summary of what container tagging is and why they should be used: https://blog.atomist.com/docker-image-tags/

We are using tags as a way of identifying important versions of containers that need to be stored on the registry. You can use tags as a way of identifying specific versions of your containers as you iterate and change them.

How to tag container images with GitLab

Within the (Surrey Shared Containers) group, We are using the GitLab CI pipeline to convert a git commit tag into a tag for your container image when published to the registry. Simply tag a commit and that version of your container image will be published to the registry with the same tag applied.

For more info on Git tags: https://git-scm.com/book/en/v2/Git-Basics-Tagging

  • Latest

    Any commits merged or pushed into the main branch on your container project will be automatically tagged with the latest tag by the CI pipeline.

    Any subsequent times you commit or merge to the main branch a new version of your container image will be built and published to the registry and the latest tag will be moved to this new version. Remember, only one version of your container can have the latest tag.

  • Custom tags

    You can also apply custom tags to your container image by using the Git tag feature on GitLab.

    • You can create a tag from a branch under Repository -> Tags you can also tag a specific commit under Repository -> Commits

    • Select the commit you wish to tag and then Options -> Tag

../_images/tag.png

Screenshot of the GitLab Repo. See Tag and Commits on the right side.

The tag you apply to the commit in your project is what will be applied as the tag when the GitLab pipeline publishes the container image to the registry.

We advise you to use sensible conventions for tagging your images. Perhaps you want to use a numerical versioning system like v.1.0.0 or perhaps you want to have a stable tag to track the latest stable version of your container image.

You can then reference these applied tags to pull this specific version of your container image: container-registry.surrey.ac.uk/shared-containers/<container-name>:<tag>