From 55dfdd0d29650f2e6102a464e746807060d95b4f Mon Sep 17 00:00:00 2001 From: Alex Kantor Date: Tue, 28 Apr 2026 14:50:28 +0100 Subject: [PATCH 1/4] docs: clarify --artifact-type=docker requires registry digest A customer hit "repo digest unavailable for the image, has it been pushed to or pulled from a registry?" after kosli attest artifact with --artifact-type=docker in CI, where the image was built but never pushed. The constraint that the docker artifact type requires a registry-resident image was only stated in the error itself. Add a note to the long descriptions of attest commands (via fingerprintDesc) and kosli fingerprint, covering the constraint and pointing at oci and dir as alternatives. Help-text only; no behaviour change. Auto-generated docs in kosli-dev/docs will pick this up on the next CLI release. Co-Authored-By: Claude Opus 4.7 (1M context) --- cmd/kosli/fingerprint.go | 5 +++++ cmd/kosli/root.go | 9 ++++++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/cmd/kosli/fingerprint.go b/cmd/kosli/fingerprint.go index 0eee34637..9f43c3b55 100644 --- a/cmd/kosli/fingerprint.go +++ b/cmd/kosli/fingerprint.go @@ -40,6 +40,11 @@ images in registries or "docker" for local docker images. Fingerprinting container images can be done using the local docker daemon or the fingerprint can be fetched from a remote registry. +Note: ^--artifact-type=docker^ reads the image's repo digest via the local Docker daemon, so +the image must have been pushed to or pulled from a registry. A freshly built image (just +^docker build^) does not have a repo digest. For images already in a registry, prefer +^--artifact-type=oci^ to fetch the digest directly from the registry. + ` + fingerprintDirSynopsis const fingerprintExamples = ` diff --git a/cmd/kosli/root.go b/cmd/kosli/root.go index 171ee6215..c21773a43 100644 --- a/cmd/kosli/root.go +++ b/cmd/kosli/root.go @@ -42,12 +42,19 @@ const ( // the following constants are used in the docs/help fingerprintDesc = ` -The artifact fingerprint can be provided directly with the ^--fingerprint^ flag, or +The artifact fingerprint can be provided directly with the ^--fingerprint^ flag, or calculated based on ^--artifact-type^ flag. Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container images in registries or "docker" for local docker images. +Note: ^--artifact-type=docker^ reads the image's repo digest via the local Docker daemon. +The image must have been pushed to or pulled from a registry for a repo digest to exist; +a freshly built image (just ^docker build^) will not have one. If the image is already in +a registry, prefer ^--artifact-type=oci^, which fetches the digest directly from the +registry without needing a local Docker daemon. To fingerprint the source instead, use +^--artifact-type=dir^ on the build context. + ` attestationBindingDesc = ` From 7848fbd710b220dbb6526636922f5690aeddbc00 Mon Sep 17 00:00:00 2001 From: Alex Kantor Date: Tue, 28 Apr 2026 16:12:09 +0100 Subject: [PATCH 2/4] docs: drop dir suggestion from artifact-type=docker note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Source-dir fingerprinting only works as an end-to-end identity if the runtime side also fingerprints the source dir. Standard Kosli runtime reporters fingerprint the running image, so suggesting dir as a generic swap is misleading — the attested and running artifacts would never link. Push and oci are the safe answers for the typical case. Co-Authored-By: Claude Opus 4.7 (1M context) --- cmd/kosli/root.go | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cmd/kosli/root.go b/cmd/kosli/root.go index c21773a43..01c376817 100644 --- a/cmd/kosli/root.go +++ b/cmd/kosli/root.go @@ -52,8 +52,7 @@ Note: ^--artifact-type=docker^ reads the image's repo digest via the local Docke The image must have been pushed to or pulled from a registry for a repo digest to exist; a freshly built image (just ^docker build^) will not have one. If the image is already in a registry, prefer ^--artifact-type=oci^, which fetches the digest directly from the -registry without needing a local Docker daemon. To fingerprint the source instead, use -^--artifact-type=dir^ on the build context. +registry without needing a local Docker daemon. ` From 413507b0df66ad9e6fc59b4dbc5c17f8791f1a21 Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Apr 2026 17:44:26 +0100 Subject: [PATCH 3/4] fix: align test data for artifact testing --- cmd/kosli/testdata/output/docs/mintlify/artifact.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/cmd/kosli/testdata/output/docs/mintlify/artifact.md b/cmd/kosli/testdata/output/docs/mintlify/artifact.md index 40d6941c5..67e7ddbec 100644 --- a/cmd/kosli/testdata/output/docs/mintlify/artifact.md +++ b/cmd/kosli/testdata/output/docs/mintlify/artifact.md @@ -16,12 +16,18 @@ artifact {IMAGE-NAME | FILE-PATH | DIR-PATH} [flags] Report an artifact creation to a Kosli flow. -The artifact fingerprint can be provided directly with the `--fingerprint` flag, or +The artifact fingerprint can be provided directly with the `--fingerprint` flag, or calculated based on `--artifact-type` flag. Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container images in registries or "docker" for local docker images. +Note: ^--artifact-type=docker^ reads the image's repo digest via the local Docker daemon. +The image must have been pushed to or pulled from a registry for a repo digest to exist; +a freshly built image (just ^docker build^) will not have one. If the image is already in +a registry, prefer ^--artifact-type=oci^, which fetches the digest directly from the +registry without needing a local Docker daemon. + ## Flags From 8c9410a513fc307a44b23ebb1119113968881229 Mon Sep 17 00:00:00 2001 From: Marko Bevc Date: Tue, 28 Apr 2026 17:53:18 +0100 Subject: [PATCH 4/4] fix: align test data for artifact testing - replace carets --- cmd/kosli/testdata/output/docs/mintlify/artifact.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cmd/kosli/testdata/output/docs/mintlify/artifact.md b/cmd/kosli/testdata/output/docs/mintlify/artifact.md index 67e7ddbec..cabada4c8 100644 --- a/cmd/kosli/testdata/output/docs/mintlify/artifact.md +++ b/cmd/kosli/testdata/output/docs/mintlify/artifact.md @@ -22,10 +22,10 @@ calculated based on `--artifact-type` flag. Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container images in registries or "docker" for local docker images. -Note: ^--artifact-type=docker^ reads the image's repo digest via the local Docker daemon. +Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon. The image must have been pushed to or pulled from a registry for a repo digest to exist; -a freshly built image (just ^docker build^) will not have one. If the image is already in -a registry, prefer ^--artifact-type=oci^, which fetches the digest directly from the +a freshly built image (just `docker build`) will not have one. If the image is already in +a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the registry without needing a local Docker daemon.