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.

[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

This workflow checks if a container image exists. If not, it builds and pushes a new version to GitHub Container Registry. It uses only the Automatic Token declared in the workflow, not a Classic PAT issued from the user account.

name: Release backup-utils image
run-name: 📦 [younsl/backup-utils] Release backup-utils image (amd64)

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

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

permissions:
  contents: read
  packages: write

jobs:
  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: |
          ENCODED_TOKEN=$(echo -n "${{ secrets.GITHUB_TOKEN }}" | base64)
          TAGS=$(curl -s -H "Authorization: Bearer ${ENCODED_TOKEN}" \
            https://ghcr.io/v2/${{ env.IMAGE_NAME }}/tags/list)
          echo "TAGS: $TAGS"

          ## Check if TAGS is empty or null
          if [[ -z "$TAGS" || "$TAGS" == "null" ]]; then
            echo "No tags found, treating as image not existing."
            echo "image_exists=false" >> $GITHUB_OUTPUT
          else
            ## Check if the specific tag already exists
            if echo "$TAGS" | jq -e --arg TAG "${{ env.BACKUP_UTILS_VERSION }}" '.tags | index($TAG)'; 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
          fi
  
  release:
    runs-on: ubuntu-latest
    needs: check
    if: ${{ needs.check.outputs.image_exists == 'false' }}
    steps:
      - name: Checkout
        id: checkout
        uses: actions/checkout@v4

      - name: Download and extract github-backup-utils
        id: prepare
        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

      - name: Login to GitHub Container Registry (ghcr.io)
        id: login
        run: |
          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
      
      - name: Build
        id: build
        run: |
          docker build \
            --platform linux/amd64 \
            -t ghcr.io/${{ env.IMAGE_NAME }}:${{ env.BACKUP_UTILS_VERSION }} github-backup-utils-v${{ env.BACKUP_UTILS_VERSION }}
            
      - name: Push
        id: push
        run: |
          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)
TAGS=$(curl -s -H "Authorization: Bearer ${ENCODED_TOKEN}" \
  https://ghcr.io/v2/${{ env.IMAGE_NAME }}/tags/list)
echo "TAGS: $TAGS"

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} issued from the user account. 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.

[younsl]

I think the same way. The only way to get the image tags list from ghcr.io registry is to use a classic PAT(though Actions Workflow supports Automatic Token) and call /tags/list API with curl command. This method is clearly not user-friendly.

[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"}]}