Using the Tag History API

Learn how to use the Chainguard Images Tag History API to fetch the tag history of image variants.

Chainguard Images have automated nightly builds, which ensures our images are always fresh including any recent patches and updated software. Even though it is important to keep your base images always updated, there will be situations where you’ll want to keep using an older build to make sure nothing will change in your container environment until you feel it’s safe to update.

For cases like this, it is useful to point your Dockerfile to use a specific image digest as base image.

An image digest is a unique identifier that is generated for each and every image build. Digests always change, even when the contents of the image remain the same.

If you have a container environment that was working fine but suddenly breaks with a new build, using a previous image build version by declaring an image digest instead of a tag is a way to keep things up and running until you’re able to assert that a new version of a container environment works as expected with your application.

Obtaining a Registry Token

Before making API calls, you’ll need to generate a token within the Chainguard Registry.

The Registry API endpoint for obtaining the token is:

https://cgr.dev/token?scope=repository:chainguard/IMAGE_NAME:pull

Where IMAGE_NAME is the name of the image that you want to pull the tag history from. It’s worth noting that the token is only valid for pulling the history of that specific image.

For public images (tagged as latest or latest-dev), you can request a registry token anonymously, without providing any pre-existing auth.

The following command will obtain a token for the Python image and register a variable called tok with the resulting value, which you can use in a subsequent command to obtain the tag history:

tok=$(curl "https://cgr.dev/token?scope=repository:chainguard/python:pull" \
  | jq -r .token)

For images that are not part of the public catalog, you’ll need to exchange your Chainguard token for a registry token. This assumes you’ve set up auth with chainctl auth configure-docker:

tok=$(curl -H "Authorization: Bearer \
  $(echo 'cgr.dev' | docker-credential-cgr get)" \
  -v "https://cgr.dev/token?scope=repository:chainguard/python:pull" \
  | jq -r .token)

To make sure your token is set, you can run the following command:

echo $tok

And you should get a long string token as output.

You should now be ready to call the API, either manually or programmatically.

Calling the API

Once you have your token available, you can run a curl query passing on your token within an Authorization: bearer header to the following endpoint:

https://cgr.dev/v2/chainguard/IMAGE_NAME/_chainguard/history/IMAGE_TAG

Where IMAGE_NAME is the name of the image, for instance: python, and IMAGE_TAG is the tag that you want to pull history from.

For example, this is how you can fetch the tag history of the python:latest Chainguard image using curl on the command line:

curl -H "Authorization: Bearer $tok" \
  https://cgr.dev/v2/chainguard/python/_chainguard/history/latest | jq

You should get output like the following:

{
  "history": [
    {
      "updateTimestamp": "2023-05-12T13:46:10.555Z",
      "digest": "sha256:81c334de6dd4583897f9e8d0691cbb75ad41613474360740824d8a7fa6a8fecb"
    },
    {
      "updateTimestamp": "2023-05-12T20:50:19.702Z",
      "digest": "sha256:a8724b7a80cae14263a3b55f7acb5d195fcbb24afbc8067aa5198aa2a9131cde"
    },
    ...

  ]
}

Using Image Digests within a Dockerfile

Setting up your Dockerfile to use an older build is a matter of modifying your FROM line to use an image digest instead of a tag. For instance, let’s say you want to make sure you keep using the current latest build of the Python image. In a previous section of this page we obtained the tag history of the Python image, and the most recent build digest is listed as sha256:81c334de6dd4583897f9e8d0691cbb75ad41613474360740824d8a7fa6a8fecb. With that information, you can edit your Dockerfile and replace:

FROM cgr.dev/chainguard/python:latest

With:

FROM cgr.dev/chainguard/python@sha256:81c334de6dd4583897f9e8d0691cbb75ad41613474360740824d8a7fa6a8fecb

And your image will then be locked into that specific build of the python:latest image variant.

Accessing the History API for Standard and Custom Images

If you are a customer who would like to access the history API for the Standard Catalog or a Custom Catalog, you must create credentials to access the API with curl and Bash.

Create Credentials

You’ll need to use credentials to access the Registry. First, authenticate with chainctl.

chainctl auth login

Next, grab your Group ID and store it in a variable.

chainctl iam groups ls -o table
export GROUP_ID="cc...52"

At this point, you can create a token for 30 days. Note that 30 days is the default, the max you can initialize a token for is 1 year.

chainctl auth configure-docker --pull-token --group $GROUP_ID --ttl 720h

If you would like to use this pull token in another environment, run this command with Docker.

docker login "cgr.dev" --username "cc..96" --password "eyJ...X34"

Be sure to keep a copy of the username and password created.

Optional: Storing Credentials

You can use the username and password you just created if required. However, Docker’s default functionality is to encode these credentials in base64 and then store them within ~/.docker/config.json.

To set that up, following the previous example, replace the username and password value, keeping the colon (:) to separate the values.

echo -n "username:password" | base64
Y2M...Wc=

Add the base64 encoded value to ~/.docker/config.json with the following format:

{
  "auths": {
    "https://cgr.dev": {
      "auth": "Y2M...Wc="
    }
  }
}

You can review more about Docker Configs from the official Docker docs.

Access the History API with curl and Bash

Now that we have the credentials, we can use curl and Bash to access the endpoints (the following example uses jq as well). Here, you will replace private-registry.com/apko with your relevant Registry and Image information.

IMAGE=private-registry.com/apko
USERNAME="cc..96"
PASSWORD="eyJ...X34"
export TOKEN=$(echo -n "${USERNAME}:${PASSWORD}" | base64 | tr -d '\n\r')
curl -s -H "Authorization: Bearer \
  $(curl -s -H "Authorization: Basic $TOKEN" \
  "https://cgr.dev/token?scope=repository:${IMAGE}:pull" | jq -r .token)" \
  "https://cgr.dev/v2/${IMAGE}/_chainguard/history/latest" | jq .

If you have set a ~/.docker/config.json file within the optional step, you can run the following.

IMAGE=private-registry.com/apko
curl -s -H "Authorization: Bearer \
  $(curl -s -H "Authorization: Basic \
  $(jq -r ".auths[\"cgr.dev\"].auth" < ~/.docker/config.json)" \
  "https://cgr.dev/token?scope=repository:${IMAGE}:pull" | jq -r .token)" \
  "https://cgr.dev/v2/${IMAGE}/_chainguard/history/latest" | jq .

Again, you would replace private-registry.com/apko with your relevant Registry and Image information.

Images Catalogs and Tags

The Public Chainguard Images Catalog is available at no cost to users, and does not require authentication. It gives access to the latest and latest-dev tags of our public images. Other versions and tags are available through subscription to our paid catalogs, featuring enterprise-grade patching SLAs and customer support.

To learn more about our image catalogs and the difference between tiers, check our Images FAQ page about catalog tiers.