GitHub Container Registry

The GitHub Container Registry (GHCR) is a component of GitHub Packages and allows users to store container images within the ImperialCollegeLondon organisation. Images can be associated with a repository and shared privately (specific users only), internally (all Imperial staff/students) or publicly. Permissions can be inherited from the repository or set independently. You can find out more information about GHCR at Working with the Container registry.

Using GHCR images in Azure

Azure supports a number of container services such as Azure Kubernetes Service, Azure Container Instances, and Azure Container Apps. With these container services, it’s possible to use a container image stored in GHCR. To do this, follow the steps below.

  1. Build and publish your image to GHCR. More details on how to do this can be found at Publishing a package using an action.

  2. Request a role account (aka service account) to be created via ASK.

  3. Once the service account has been created, login to the ImperialCollegeLondon organisation as the service account.

  4. After logging in via Imperial Single-sign on (SSO), you’ll be asked to create a GitHub account. This account should also be created under the service account. We recommend adding a shared mailing list (aka DL) as a verified email address in the GitHub settings of the service account. This ensures any GitHub emails/alerts are sent to the shared mailbox as well as the service account mailbox.

  5. Add the service account to the repository and assign the relevant permissions. The Read role should be sufficient.

  6. Create a classic personal access token (PAT) for the service account with the read:packages scope.

  7. Use this PAT token along with the variables below to pull the image from GHCR using your chosen Azure container service. The variable names may change depending on which Azure service you’re using. However, the values will remain the same.

Variable Name Description
IMAGE The full image name in GHCR, e.g. ghcr.io/imperialcollegelondon/my-repo/my-image:1.0.1
IMAGE_REGISTRY_LOGIN_SERVER The registry URL, typically ghcr.io
IMAGE_REGISTRY_USERNAME The GitHub username of the service account
IMAGE_REGISTRY_PASSWORD The personal access token (PAT) for the service account

Container image tagging best practices

When publishing container images to GHCR, it’s important to use a robust tagging strategy. Proper tagging ensures reproducibility, simplifies debugging, and enables reliable rollbacks.

Avoid using the “latest” tag

Do not use the latest tag as your primary tagging strategy. The latest tag is widely recognised as bad practice.

The latest tag creates several problems:

  • Lack of reproducibility: When you reference latest, you don’t know which specific version of the image you’re using. This makes it difficult to reproduce builds or deployments consistently across environments.
  • Debugging difficulties: If an issue occurs, you cannot easily identify which version of the code was running because latest constantly changes.
  • Rollback challenges: Rolling back to a previous version becomes nearly impossible because latest doesn’t preserve historical versions.
  • Breaking changes: The latest tag can introduce unexpected breaking changes into production environments without warning.
  • Cache confusion: Container runtimes may cache latest images, meaning you might not get the most recent version even when you expect to.

Instead of using latest, consider these alternative approaches:

Semantic versioning (semver)

Use semantic versioning to tag your images with meaningful version numbers:

  • ghcr.io/imperialcollegelondon/my-repo/my-image:1.0.0 - Initial release
  • ghcr.io/imperialcollegelondon/my-repo/my-image:1.0.1 - Patch release (bug fixes)
  • ghcr.io/imperialcollegelondon/my-repo/my-image:1.1.0 - Minor release (new features, backwards compatible)
  • ghcr.io/imperialcollegelondon/my-repo/my-image:2.0.0 - Major release (breaking changes)

This approach makes it clear what changes to expect between versions and ensures you can always reference a specific version. You can find more information at semver.org.

Git commit SHA

Tag images with the Git commit SHA from which they were built:

  • ghcr.io/imperialcollegelondon/my-repo/my-image:sha-a1b2c3d

This creates a direct link between your code and your container image, making it easy to trace issues back to specific commits.

GitHub Actions run ID or number

Tag images using the GitHub Actions workflow run ID or run number:

  • ghcr.io/imperialcollegelondon/my-repo/my-image:run-123456789
  • ghcr.io/imperialcollegelondon/my-repo/my-image:build-42

This approach is particularly useful when images are automatically built via CI/CD pipelines.

You can apply multiple tags to the same image. For example, you might tag an image with both a semantic version (1.0.0) and a commit SHA (sha-a1b2c3d) to provide flexibility whilst maintaining traceability.

Further reading