How to check if a container image exists on GHCR?

[ten-chh]

I’m using GHCR as my container registry. The GitOps automation we use breaks if an engineer specifies an image that doesn’t exist. For example, if the last built image is ghcr.io/my-company/my-image:1.0 but the engineer specifies ghcr.io/my-company/my-image:1.1 the automation breaks.

Is there a way use the GHCR v2 http API or the GitHub API to check if a specific image/tag combination exists? And what PAT scopes are needed for the check (if it is available)?

[airtower-luna]

GHCR supports the Docker Registry API. You could either try to download the specific tag and see if you get a valid manifest, or retrieve the list of tags and check if the tag shows up. You’ll need to use a token with read:packages scope for the requests.

That said, maybe it’s better to catch and handle the error that currently occurs instead of adding a separate check? After all, the error occurring already tells you that the tag doesn’t exist. 😉

[ten-chh]

I’m asking specifically because other topics reference portions of the Docker Registry API that haven’t been implemented yet (e.g. /v2/_catalog - Ghcr.io docker HTTP API). When I attempt to use the /v2/<name>/tags/list API endpoint, I get {"errors":[{"code":"UNAUTHORIZED","message":"authentication token not provided"}]}. But using the same username and PAT I’m able to successfully access the /v2/ API endpoint. I double-checked that the user has Read access to the GHCR package that I’m trying to access.

Additionally, we are using a third-party GitOps package which breaks when it tries to install an image that doesn’t exist. So we’re opting to check the GitOps definition during the lint/test phrase before even executing the GitOps process.

[clarkbw]

You can use the tags/list endpoint to grab all available tags.

You’ll need a token for this like a PAT. (soon this will work with the GITHUB_TOKEN)

Here’s an example:

# for a public image you can get a fake NOOP token to use
curl https://ghcr.io/token\?scope\="repository:USER/IMAGE:pull"
{"token":"{TOKEN}"}
curl -H "Authorization: Bearer {TOKEN}" https://ghcr.io/v2/USER/IMAGE/tags/list
{"name":"USER/IMAGE","tags":["2.7.5-arm64","2.7.5-armhf","2.7.5-amd64"]}

[13013SwagR]

Now that ghcr.io supports GITHUB_TOKEN, you can do the following

GHCR_TOKEN=$(echo ${{ secrets.GITHUB_TOKEN }} | base64)
# To list tags
curl -H "Authorization: Bearer ${GHCR_TOKEN}" https://ghcr.io/v2/USER/IMAGE/tags/list
# To pull manifest
OLD_TAG=test
MANIFEST=$(curl -H "Authorization: Bearer ${GHCR_TOKEN}" https://ghcr.io/v2/USER/IMAGE/manifests/$OLD_TAG)
# To push a new tag
CONTENT_TYPE="application/vnd.docker.distribution.manifest.v2+json"
NEW_TAG=latest
curl -f -X PUT -H "Content-Type: ${CONTENT_TYPE}" -H "Authorization: Bearer ${GHCR_TOKEN}"  -d "${MANIFEST}" "https://ghcr.io/v2/USER/IMAGE/manifests/$NEW_TAG"

Cheers

[tsnobip]

this should be the answer now

[austinworks]

super helpful. the first curl example is missing a $ though, it should be as follows:

# To list tags
curl -H "Authorization: Bearer ${GHCR_TOKEN}" https://ghcr.io/v2/USER/IMAGE/tags/list

[victorlin]

Why does the GitHub token have to be base64-encoded?

[NiceGuyIT]

GHCR_TOKEN=$(echo ${{ secrets.GITHUB_TOKEN }} | base64)

While this works, it's missing one important piece of information: -n! That's right! The trailing newline is required to be included in the base64 encoding for authentication to succeed. The GitHub developer doesn't know BASH (shell scripting?) well enough to know that -n should be added to all echo -n "${SOME_STRING}" to prevent the trailing newline from being interpreted in the down pipe (next command). Yeah, I wasted a little bit of time on this wondering why I'm getting authorization denied when using a language that properly trims whitespace before encoding.

[HenryTen]

Would you like a step-by-step explanation of each command shown (e.g., listing tags, pulling manifests, pushing new tags)?

[miohtama]

Based on @13013SwagR’s answer, here is my shell script version for Bash/command line.

Creating Personal Access Token (PAT) to access Github container registry

• Go to Personal tokens in Github Developer settings.
• Generate new token
• Save the token in the password manager
• Select the read:packages scope to download container images and read their metadata.
• Select the write:packages scope to download and upload container images and read and write their metadata.
• Select the delete:packages scope to delete container images.

Listing available tags for a container on GHCR

First set your PAT in GITHUB_TOKEN environment variable

echo $GITHUB_TOKEN

Should give your PAT token that looks lke:

ghp_mmc...

The PAT needs to be converted to base64 encoding for GHCR REST API.

export GHCR_TOKEN=$(echo $GITHUB_TOKEN | base64)

To list tags for organisation/user myorg for project myproject

curl -H "Authorization: Bearer $GHCR_TOKEN" https://ghcr.io/v2/myorg/myproject/tags/list

You should get a JSON reply like:

{"name":"myorg/myproject","tags":["pr-58"]}

Here is also our Github Actions build recipe how to build and push images to GCHR.

[KES777]

How to delete pushed image?

export GH_TOKEN=`cat jenkins | base64` && curl --fail -H "Authorization: Bearer $GH_TOKEN" -X DELETE https://ghcr.io/v2/org/repo/manifests/sha256:b69a90aedbaf76b83af2d89c61c22a9c3bd683912e8ef58eb7166be86e70a5bf

I get curl: (22) The requested URL returned error: 405. What is the problem here?

[airtower-luna]

It seems you're trying to use the Docker registry API. GHCR doesn't allow deleting that way, you need to use the packages API. If you need more help please create a new thread, because you're asking a new question.

[mcandre]

REST services are okay, but what would really help users out is a basic search frontend, like Docker Hub enjoys.

[baylf2000]

PLEASE!

[relsqui]

or even a command in the github cli

[Ayushi-gupta2001]

How can we list all the docker images that we have on the GitHub container registry?

[airtower-luna]

See here for your user packages (with package_type=container): https://docs.github.com/en/rest/packages?apiVersion=2022-11-28#list-packages-for-the-authenticated-users-namespace

Same thing for an organization: https://docs.github.com/en/rest/packages?apiVersion=2022-11-28#list-packages-for-an-organization

[mmm8955405]

It's difficult to query without a webui

[Adriansillo]

where is the documentation to use the API ?
i am using the tags/list endpoint but want to know about more useful endpoints

[younsl]

Hi fellas. I hope my use case will be helpful to many people.

Here is the workflow to check if a container image exists and push it to ghcr.io.

Solutions

Example Workflow

name: Build and push container image (amd64)
run-name: 🚚 [backup-utils] Build and push container image

on:
  workflow_dispatch:
    inputs:
      BACKUP_UTILS_VERSION:
        description: 'Version of github-backup-utils to use'
        required: true
        default: '3.14.0'

env:
  BACKUP_UTILS_VERSION: ${{ github.event.inputs.BACKUP_UTILS_VERSION }}
  IMAGE_NAME: younsl/backup-utils

permissions:
  contents: read
  packages: write

jobs:
  # Job 1: Check if the image with the tag already exists on GitHub Container Registry
  check:
    runs-on: ubuntu-latest
    outputs:
      image_exists: ${{ steps.image_check.outputs.image_exists }}
    steps:
      - name: Check if image exists on GitHub Container Registry
        id: image_check
        run: |
          echo "Checking if image with tag ${{ env.BACKUP_UTILS_VERSION }} exists on ghcr.io ..."

          # Fetch the list of tags from GitHub Container Registry
          ENCODED_TOKEN=$(echo -n "${{ secrets.GITHUB_TOKEN }}" | base64)
          TAG_EXISTS=$(curl -s -H "Authorization: Bearer ${ENCODED_TOKEN}" \
            https://ghcr.io/v2/${{ env.IMAGE_NAME }}/tags/list \
            | jq -r --arg TAG "${{ env.BACKUP_UTILS_VERSION }}" '.tags[] | select(. == $TAG)')

          # Check if the tag exists
          if [[ -n "$TAG_EXISTS" ]]; then
            echo "Image with tag ${{ env.BACKUP_UTILS_VERSION }} already exists."
            echo "image_exists=true" >> $GITHUB_OUTPUT
          else
            echo "Image with tag ${{ env.BACKUP_UTILS_VERSION }} not found."
            echo "image_exists=false" >> $GITHUB_OUTPUT
          fi
  
  # Job 2: Build and push the container image if it does not exist
  release:
    runs-on: ubuntu-latest
    needs: check
    if: ${{ needs.check.outputs.image_exists == 'false' }}  # Only run if the image doesn't exist
    steps:
      # Step 1: Checkout the repository
      - name: Checkout code
        uses: actions/checkout@v3

      # Step 2: Download and extract github-backup-utils
      - name: Download and extract github-backup-utils
        run: |
          echo "Downloading github-backup-utils version ${{ env.BACKUP_UTILS_VERSION }} ..."
          curl -L -o github-backup-utils-${{ env.BACKUP_UTILS_VERSION }}.tar.gz \
            https://github.com/github/backup-utils/releases/download/v${{ env.BACKUP_UTILS_VERSION }}/github-backup-utils-v${{ env.BACKUP_UTILS_VERSION }}.tar.gz
          
          echo "Extracting github-backup-utils tarball..."
          tar -xzf github-backup-utils-${{ env.BACKUP_UTILS_VERSION }}.tar.gz
      
      # Step 3: Build the Docker image for amd64
      - name: Build container image (amd64)
        run: |
          echo "Building Docker image for amd64 architecture: ghcr.io/${{ env.IMAGE_NAME }}:${{ env.BACKUP_UTILS_VERSION }} ..."
          docker build \
            --platform linux/amd64 \
            -t ghcr.io/${{ env.IMAGE_NAME }}:${{ env.BACKUP_UTILS_VERSION }} github-backup-utils-v${{ env.BACKUP_UTILS_VERSION }}
      
      # Step 4: Log in to GitHub Container Registry
      - name: Log in to GitHub Container Registry
        run: |
          echo "Logging in to GitHub Container Registry ..."
          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
      
      # Step 5: Push the Docker image to GitHub Container Registry for amd64
      - name: Push container image (amd64)
        run: |
          echo "Pushing Docker image ghcr.io/${{ env.IMAGE_NAME }}:${{ env.BACKUP_UTILS_VERSION }} to ghcr.io ..."
          docker push ghcr.io/${{ env.IMAGE_NAME }}:${{ env.BACKUP_UTILS_VERSION }}

Key Points

1. List image tags using /tags/list API

This API retrieves a list of all image tags in your ghcr.io repository.

2. Base64 encoding for Authorization

The bearer token must be Base64-encoded before making /tags/list API call.

Example for encoding the token in a GitHub Actions workflow:

# Actions Workflow file (release.yml)
ENCODED_TOKEN=$(echo -n "${{ secrets.GITHUB_TOKEN }}" | base64)
TAG_EXISTS=$(curl -s -H "Authorization: Bearer ${ENCODED_TOKEN}" \
  https://ghcr.io/v2/${{ env.IMAGE_NAME }}/tags/list \
  | jq -r --arg TAG "${{ env.BACKUP_UTILS_VERSION }}" '.tags[] | select(. == $TAG)')

3. Automatic Token for Authentication

Warning

Only applicable if you use Actions Workflow. If you are running the script in your local environment, you will still need the actual user's Classic Personal Access Token.

You don't need to use a Classic PAT^{Personal Access Token}. GitHub's Automatic Token^{${{ secrets.GITHUB_TOKEN }}} handles all operations securely without requiring periodic renewals.

4. Permission Issues on Push

If you encounter a denied: permission_denied: write_package error after successfully login to ghcr.io, it means the workflow lacks the necessary permissions to push the Docker image. Ensure that the workflow has the proper access to the package in GitHub Packages. You can adjust the permissions in the repository’s settings under Manage Actions access, and verify that the workflow repository is granted write permission.

Common denied: permission_denied Error Example:

Pushing Docker image ghcr.io/<USERNAME>/<IMAGE_NAME>:3.14.0 to ghcr.io ...
The push refers to repository [ghcr.io/<USERNAME>/<IMAGE_NAME>]
...
3ec3ded77c0c: Preparing
denied: permission_denied: write_package

Note

Check that the appropriate write permissions are granted under Packages settings. See Publishing and installing a package with GitHub Actions and Publishing images to GitHub Packages.

[ozbillwang]

Any WebUI recommend to go through GHCR images from Github Container registry (GHCR)?

[kiloforce]

I am confused. It is really great that GitHub provides a Docker Registry. Even better that Docker images can be used with GitHub Actions. But, I don't understand how the ability to do basic maintenance is missing? Even if not by API, there should be a basic way to view exiting Docker images, under your account, and delete old cruft, especially if there is a security concern found, right? I don't see any mention of how to do either of these steps mentioned on either of the Docker Registry pages? Is this documented somewhere else?

Working with the Docker registry - GitHub Docs
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-docker-registry

Working with the Container registry - GitHub Docs
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

[i-am-mike-davis]

As a user of a project that publishes container images on ghcr, I would really appreciate the ability to view what images are available without having to find my GitHub token, open my terminal, and run a curl command.

[argh]

Our orchestration framework pings the registry for images for the "latest" hashes so we can see if we're behind. One of our dependencies switched to ghcr, and we're getting authentication errors when we try to list tags for this image. As a consumer of public docker images, it's really weird that I can't anonymously list tags for a public image without a token.

curl --verbose https://ghcr.io/v2/wg-easy/wg-easy/tags/list yields {"errors":[{"code":"UNAUTHORIZED","message":"authentication required"}]}