# Docker Digest<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10007;
|===

== Description

The `dockerdigest` resource resolves a container image tag to the digest it currently points at, so deployments can pin an immutable reference instead of a mutable tag.

**source**::
Returns the digest for `image` and `tag`, in the form `jenkins/jenkins:lts-jdk11@sha256:...`.

**condition**::
Checks that an image exists in the registry for the given digest - `digest` when set, otherwise the source output. A missing image reports `the Docker image <ref> doesn't exist.` rather than erroring.

**target**::
Not supported - a target fails with `Target not supported for the plugin Docker Digest`. Write the digest into a file with the link:/docs/plugins/resource/yaml/["Yaml"] or link:/docs/plugins/resource/file/["File"] resources.

NOTE: An `scm` is accepted but ignored, logging `scm is not supported, ignoring`. The lookup always goes to the registry.

== Parameters

{{< resourceparameters "sources" "dockerdigest" >}}

`image`:: Mandatory, e.g. `updatecli/updatecli`.
`tag`:: Defaults to `latest`. It must not already contain a digest (a value starting with `@` is rejected with `invalid tag <image>: only contain a digest`).
`architecture`:: Defaults to `amd64`. Unset, the digest returned is that of the **image index**, valid on any platform; set, it is the digest of that one platform's image. The two are different values for the same tag.
`digest`:: Condition only, defaulting to the source output.
`hidetag`:: Source only. Changes the shape of the returned value.

=== hidetag

By default the source keeps the tag alongside the digest, which stays readable in a diff while still pinning the exact image:

[source,text]
----
index.docker.io/jenkins/jenkins:lts-jdk11@sha256:ce782db15ab...
----

With `hidetag: true` the tag is dropped:

[source,text]
----
index.docker.io/jenkins/jenkins@sha256:ce782db15ab...
----

== Authentication

Credentials are given inline on the spec. Depending on the registry, how you obtain a token differs.

IMPORTANT: Storing credentials in an unencrypted manifest is a bad practice. Read them from the environment with `'{{ requiredEnv "TOKEN" }}'`.

=== GHCR

GitHub uses a personal access token (see link:https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token[Creating a personal access token]).

=== DockerHub

The simplest route is to run `docker login` and read the token from `~/.docker/config.json`:

[source,json]
----
"auths": {
        "https://index.docker.io/v1/": {
                "auth": "token"
        }
},
----

== Example

This example uses a Go template, `updatecli.tpl`, with values from `values.yaml`, so that `{{ requiredEnv "..." }}` can read the GitHub token from the environment.

[source,yaml]
----
# updatecli.tpl
sources:
  lastDockerDigest:
    kind: dockerdigest
    spec:
      image: "jenkins/jenkins"
      tag: "lts-jdk11"
targets:
  imageTag:
    name: "jenkins/jenkins:lts-jdk11 docker digest"
    kind: yaml
    spec:
      file: "config/default/jenkins-release.yaml"
      key: "jenkins.master.imageTag"
    scm:
      github:
        user: "{{ .github.user }}"
        email: "{{ .github.email }}"
        owner: "jenkins-infra"
        repository: "charts"
        token: "{{ requiredEnv .github.token }}"
        username: "{{ .github.username }}"
        branch: "master"
----

[source,yaml]
----
# values.yaml
github:
  user: "updatebot"
  email: "updatebot@olblak.com"
  username: "jenkins-infra-bot"
  token: "UPDATECLI_GITHUB_TOKEN"
  branch: "master"
  owner: "olblak"
  repository: "charts"
----

What it says:

**Source**::
Retrieve the digest of `jenkins/jenkins:lts-jdk11` from DockerHub.

**Target**::
Update the YAML key `jenkins.master.imageTag` in `config/default/jenkins-release.yaml` in the GitHub repository `jenkins-infra/charts`.

== Links

* link:/docs/plugins/resource/docker_image/[The `dockerimage` resource] - to find a tag rather than resolve one