diff --git a/.github/workflows/__test-action-get-image-metadata.yml b/.github/workflows/__test-action-get-image-metadata.yml index 49ff463e..484b6b52 100644 --- a/.github/workflows/__test-action-get-image-metadata.yml +++ b/.github/workflows/__test-action-get-image-metadata.yml @@ -8,6 +8,141 @@ on: # yamllint disable-line rule:truthy permissions: {} jobs: + candidate-contracts: + name: Assert candidate identity and metadata policy + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const assert = require('node:assert/strict'); + const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor; + const { stdout } = await exec.getExecOutput('ruby', [ + '-rjson', '-ryaml', '-e', 'puts JSON.generate(YAML.safe_load(File.read(ARGV[0])))', + 'actions/docker/get-image-metadata/action.yml', + ]); + const steps = JSON.parse(stdout).runs.steps; + const image = 'ghcr.io/example/app'; + const revision = 'a'.repeat(40); + const baseEnv = { + INPUT_CANDIDATE: 'true', GITHUB_REPOSITORY_ID: '123', GITHUB_REPOSITORY: 'example/app', + GITHUB_RUN_ID: '456', GITHUB_RUN_ATTEMPT: '1', IMAGE_NAME_WITH_REGISTRY: image, + DOCKER_METADATA_LABELS: `org.opencontainers.image.revision=${revision}\norg.opencontainers.image.version=main`, + DOCKER_METADATA_ANNOTATIONS: 'manifest:org.opencontainers.image.version=main', + DOCKER_METADATA_TAGS: `${image}:main\n${image}:latest`, + DEFAULT_BRANCH: 'main', GH_REF: 'refs/heads/main', ISSUE_NUMBER: '12', + }; + async function evaluate(id, overrides = {}, eventName = 'push') { + const outputs = {}; + const env = { ...baseEnv, ...overrides }; + try { + await new AsyncFunction('require', 'process', 'context', 'core', steps.find(step => step.id === id).with.script)( + require, { env }, { eventName, ref: env.GH_REF }, { + setOutput: (key, value) => { outputs[key] = value; }, + setFailed: message => { throw new Error(message); }, + }, + ); + } catch (error) { + if (id === 'generate-outputs') assert.equal(outputs.tags, undefined, 'Invalid candidates must expose no publication tags'); + throw error; + } + return outputs; + } + const first = await evaluate('generate-outputs'); + const second = await evaluate('generate-outputs'); + assert.match(first.tags, /^ghcr\.io\/example\/app:candidate-123-456-1-[a-f0-9-]{36}$/); + assert.notEqual(first.tags, second.tags, 'Repeated calls must not share a temporary tag'); + assert.equal(first.labels, baseEnv.DOCKER_METADATA_LABELS); + assert.equal(first.annotations, baseEnv.DOCKER_METADATA_ANNOTATIONS); + assert.deepEqual(JSON.parse(first.candidate), { + destinations: [`${image}:main`, `${image}:latest`], + source: { repository: 'example/app', revision }, run: { id: '456', attempt: '1' }, + }); + const normal = await evaluate('generate-outputs', { INPUT_CANDIDATE: 'false' }); + assert.equal(normal.tags, baseEnv.DOCKER_METADATA_TAGS); + assert.equal(normal.candidate, undefined); + for (const [key, value, prefix] of [ + ['GITHUB_RUN_ATTEMPT', '2', 'candidate-123-456-2-'], + ['GITHUB_RUN_ID', '789', 'candidate-123-789-1-'], + ['GITHUB_REPOSITORY_ID', '987', 'candidate-987-456-1-'], + ]) { + assert((await evaluate('generate-outputs', { [key]: value })).tags.startsWith(`${image}:${prefix}`)); + } + for (const key of ['GITHUB_REPOSITORY_ID', 'GITHUB_RUN_ID', 'GITHUB_RUN_ATTEMPT']) { + for (const value of ['', '0', '-1', '1\nother', 'no']) { + await assert.rejects(evaluate('generate-outputs', { [key]: value }), /requires repository, run and attempt IDs/); + } + } + for (const overrides of [ + { GITHUB_REPOSITORY: '' }, { DOCKER_METADATA_LABELS: 'org.opencontainers.image.revision=invalid' }, + { DOCKER_METADATA_TAGS: '' }, { DOCKER_METADATA_TAGS: 'ghcr.io/other/app:main' }, + ]) { + await assert.rejects(evaluate('generate-outputs', overrides), /Candidate publication requires/); + } + for (const value of ['', 'yes', 'TRUE']) { + await assert.rejects(evaluate('define-metadata-inputs', { INPUT_CANDIDATE: value }), /must be true or false/); + } + for (const [event, overrides, expected] of [ + ['push', {}, { flavor: 'latest=true', tags: 'type=ref,event=branch' }], + ['pull_request', { GH_REF: 'refs/pull/12/merge' }, { flavor: 'latest=false', tags: 'type=sha,prefix=pr-12-\ntype=ref,event=pr' }], + ['push', { GH_REF: 'refs/tags/v1.2.3' }, { flavor: 'latest=false', tags: 'type=ref,event=tag' }], + ['push', { INPUT_TAG: '1.2.3' }, { tags: 'type=raw,value=1.2.3', flavor: 'latest=false' }], + ]) { + assert.deepEqual(await evaluate('define-metadata-inputs', overrides, event), expected); + } + + candidate-metadata: + name: Test candidate metadata (${{ matrix.tag || 'event tags' }}) + runs-on: ubuntu-latest + strategy: + matrix: + tag: ["", "1.2.3"] + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - id: normal + uses: $/actions/docker/get-image-metadata + with: + image: application-test + tag: ${{ matrix.tag }} + + - id: candidate + uses: $/actions/docker/get-image-metadata + with: + image: application-test + tag: ${{ matrix.tag }} + candidate: true + + - name: Assert metadata and destinations + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + NORMAL: ${{ toJSON(steps.normal.outputs) }} + CANDIDATE: ${{ toJSON(steps.candidate.outputs) }} + with: + script: | + const assert = require('node:assert/strict'); + const normal = JSON.parse(process.env.NORMAL); + const candidate = JSON.parse(process.env.CANDIDATE); + const withoutCreationTime = value => value.split('\n').filter(line => !line.includes('org.opencontainers.image.created=')); + assert.equal(candidate.image, normal.image); + for (const key of ['labels', 'annotations']) { + assert.deepEqual(withoutCreationTime(candidate[key]), withoutCreationTime(normal[key])); + } + assert.deepEqual(JSON.parse(candidate.candidate).destinations, normal.tags.split('\n')); + assert.equal(candidate.tags.split('\n').length, 1); + assert(candidate.tags.startsWith(`${normal.image}:candidate-${process.env.GITHUB_REPOSITORY_ID}-${context.runId}-${process.env.GITHUB_RUN_ATTEMPT}-`)); + assert(!normal.tags.split('\n').includes(candidate.tags)); + tests: name: Test for "docker/get-image-metadata" action runs-on: ubuntu-latest diff --git a/.github/workflows/__test-workflow-docker-build-images-building.yml b/.github/workflows/__test-workflow-docker-build-images-building.yml index b14ff6ff..65ec85b4 100644 --- a/.github/workflows/__test-workflow-docker-build-images-building.yml +++ b/.github/workflows/__test-workflow-docker-build-images-building.yml @@ -12,6 +12,40 @@ permissions: {} # jscpd:ignore-start jobs: + candidate-inputs: + name: Assert candidate workflow image selection + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const assert = require('node:assert/strict'); + const { stdout } = await exec.getExecOutput('ruby', [ + '-rjson', '-ryaml', '-e', 'puts JSON.generate(YAML.safe_load(File.read(ARGV[0])))', + '.github/workflows/docker-build-images.yml', + ]); + const script = JSON.parse(stdout).jobs['prepare-variables'].steps.find(step => step.id === 'validate-inputs').with.script; + const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor; + async function validate(images) { + const outputs = {}; + await new AsyncFunction('process', 'context', 'core', script)( + { env: { CANDIDATE_INPUT: 'true', OCI_REGISTRY_PASSWORD: 'fixture', RUNS_ON_INPUT: '["ubuntu-latest"]', IMAGES_INPUT: JSON.stringify(images) } }, + { repo: { owner: 'example', repo: 'app' } }, { setOutput: (key, value) => { outputs[key] = value; } }, + ); + return JSON.parse(outputs.images); + } + const single = { name: 'single', platforms: ['linux/amd64'], tag: '1.2.3' }; + const multi = { name: 'multi', platforms: ['linux/amd64', 'linux/arm64'] }; + assert.equal((await validate([single, multi])).length, 2); + await assert.rejects(validate([]), /non-empty list with unique image names/); + await assert.rejects(validate([single, { ...single, target: 'other' }]), /unique image names/); + act-build-images-args-secrets: name: Arrange - Build with args, secrets uses: $/.github/workflows/docker-build-images.yml @@ -89,4 +123,161 @@ jobs: assert(builtImages[image], `"built-images" output does not contain "${image}" image`); } + act-candidates: + name: Build signed candidates with final metadata + uses: $/.github/workflows/docker-build-images.yml + permissions: + attestations: write + contents: read + id-token: write + issues: read + packages: write + pull-requests: read + secrets: + oci-registry-password: ${{ secrets.GITHUB_TOKEN }} + with: + candidate: true + images: | + [ + { + "name": "test-candidate-${{ github.run_id }}-${{ github.run_attempt }}-single", + "dockerfile": "tests/application/Dockerfile", + "target": "base", + "platforms": ["linux/amd64"], + "tag": "1.2.3" + }, + { + "name": "test-candidate-${{ github.run_id }}-${{ github.run_attempt }}-multi", + "dockerfile": "tests/application/Dockerfile", + "target": "base", + "platforms": ["linux/amd64", "linux/arm64"], + "tag": "1.2.3" + } + ] + + assert-candidates: + name: Assert candidate outputs, tags and security metadata + needs: act-candidates + runs-on: ubuntu-latest + permissions: + contents: read + packages: read + attestations: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: $/actions/docker/setup + with: + oci-registry: ghcr.io + oci-registry-username: ${{ github.repository_owner }} + oci-registry-password: ${{ secrets.GITHUB_TOKEN }} + + - uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3 + + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + BUILT_IMAGES: ${{ needs.act-candidates.outputs.built-images }} + GH_TOKEN: ${{ github.token }} + with: + script: | + const assert = require('node:assert/strict'); + const images = Object.values(JSON.parse(process.env.BUILT_IMAGES)); + assert.equal(images.length, 2); + for (const image of images) { + const repository = `${image.registry}/${image.repository}`; + assert.deepEqual(image.candidate.destinations, [`${repository}:1.2.3`]); + assert.equal(image.candidate.source.repository, process.env.GITHUB_REPOSITORY); + assert.match(image.candidate.source.revision, /^[a-f0-9]{40}$/); + assert.deepEqual(image.candidate.run, { + id: process.env.GITHUB_RUN_ID, attempt: process.env.GITHUB_RUN_ATTEMPT, + }); + assert.equal(image.tags.length, 1); + assert(image.tags[0].startsWith(`candidate-${process.env.GITHUB_REPOSITORY_ID}-${context.runId}-${process.env.GITHUB_RUN_ATTEMPT}-`)); + assert.deepEqual(image.images, [`${repository}:${image.tags[0]}@${image.digest}`]); + const reference = `${repository}@${image.digest}`; + const { stdout: inspected } = await exec.getExecOutput('docker', ['buildx', 'imagetools', 'inspect', `${repository}:${image.tags[0]}`]); + assert.equal(inspected.match(/Digest:\s+(sha256:[a-f0-9]{64})/)[1], image.digest); + const { stdout: raw } = await exec.getExecOutput('docker', ['buildx', 'imagetools', 'inspect', '--raw', reference]); + const manifest = JSON.parse(raw); + if (image.name.endsWith('-multi')) { + assert.deepEqual(manifest.manifests.map(item => `${item.platform.os}/${item.platform.architecture}`).sort(), ['linux/amd64', 'linux/arm64']); + assert.equal(manifest.annotations['org.opencontainers.image.version'], '1.2.3'); + } else { + assert(manifest.config, 'Single-platform candidate must retain its image manifest'); + } + await exec.exec('docker', ['pull', '--platform', 'linux/amd64', reference]); + const { stdout: config } = await exec.getExecOutput('docker', ['image', 'inspect', reference]); + const labels = JSON.parse(config)[0].Config.Labels; + assert.equal(labels['org.opencontainers.image.version'], '1.2.3'); + assert.equal(labels['org.opencontainers.image.revision'], image.candidate.source.revision); + const versions = await github.paginate(github.rest.packages.getAllPackageVersionsForPackageOwnedByOrg, { + package_type: 'container', package_name: `${context.repo.repo}/${image.name}`, + org: context.repo.owner, per_page: 100, + }); + const tags = versions.flatMap(version => version.metadata.container.tags); + assert(tags.includes(image.tags[0])); + assert(tags.every(tag => tag === image.tags[0] || tag.startsWith('sha256-')), `Unexpected consumer tag: ${tags}`); + await exec.exec('cosign', [ + 'verify', '--certificate-oidc-issuer', 'https://token.actions.githubusercontent.com', + '--certificate-identity-regexp', `^https://github.com/${process.env.GITHUB_REPOSITORY}/`, reference, + ]); + await exec.exec('gh', ['attestation', 'verify', `oci://${reference}`, '--repo', process.env.GITHUB_REPOSITORY]); + } + + failed-candidate: + name: Assert failed builds have no candidate output + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - id: failed-build + continue-on-error: true + uses: $/actions/docker/build-image + with: + image: test-candidate-${{ github.run_id }}-${{ github.run_attempt }}-failed + dockerfile: tests/application/Dockerfile + target: test + platform: linux/amd64 + candidate: true + tag: "1.2.3" + cache-type: "false" + # The existing test stage rejects missing mandatory build arguments. + + - name: Assert failure without outputs + env: + OUTCOME: ${{ steps.failed-build.outcome }} + BUILT_IMAGE: ${{ steps.failed-build.outputs.built-image }} + run: | + test "$OUTCOME" = failure + test -z "$BUILT_IMAGE" + + cleanup-candidates: + name: Clean isolated candidate test packages + if: always() + needs: [act-candidates, assert-candidates, failed-candidate] + runs-on: ubuntu-latest + permissions: + packages: write + steps: + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + for (const suffix of ['single', 'multi', 'failed']) { + const name = `test-candidate-${context.runId}-${process.env.GITHUB_RUN_ATTEMPT}-${suffix}`; + try { + await github.rest.packages.deletePackageForOrg({ + package_type: 'container', package_name: `${context.repo.repo}/${name}`, org: context.repo.owner, + }); + } catch (error) { + if (error.status !== 404) throw error; + } + } + # jscpd:ignore-end diff --git a/.github/workflows/docker-build-images.md b/.github/workflows/docker-build-images.md index 5197450d..3a83b72d 100644 --- a/.github/workflows/docker-build-images.md +++ b/.github/workflows/docker-build-images.md @@ -29,6 +29,23 @@ Build images using [Docker build image](../../actions/docker/build-image/README. This includes [multi-platform](https://docs.docker.com/build/building/multi-platform/) build. See [Build caches](../../actions/docker/build-image/README.md#build-caches) for cache behavior and recovery. +## Candidate builds + +Set `candidate: true` to publish temporary images for validation. Keep the existing +image configuration; `images[].tag`, when provided, describes the final tag and +OCI version. The workflow generates unique repository/run/attempt-scoped tags +and leaves normal PR, branch, release and `latest` tags untouched. Signing and +attestations follow the existing inputs. Use digest-qualified `built-images` +references in downstream tests. + +Each candidate entry adds `candidate.destinations` (normal full tagged references), +`candidate.source` (`repository` and metadata `revision`) and `candidate.run` +(`id` and `attempt` as strings). These describe the build, not successful validation. +The workflow does not promote candidates or delete them automatically. Keep +production publication gated until a validated promotion mechanism is available. +Never delete a registry version that has acquired consumer tags. +See [ADR 0005](../../docs/adr/0005-publish-candidates-with-final-image-metadata.md). + ### Permissions - **`attestations`**: `write` @@ -148,6 +165,11 @@ jobs: # Default: `true` lfs: true + # Publish under unique temporary tags while retaining intended OCI metadata. + # Normal tags are recorded in `built-images` as `candidate.destinations` and + # are not published. No promotion or automatic cleanup is performed. + candidate: false + # Environment variable name(s) to pass GitHub token generated by GitHub App. # Can be a multiline string list. # This is useful to pass a generated token to the build, as it is not possible to share generated secrets between jobs. @@ -235,6 +257,9 @@ jobs: | |
[
{
"name": "application",
"context": ".",
"dockerfile": "./docker/application/Dockerfile",
"target": "prod",
"build-args": {
"APP_PATH": "./application/",
"PROD_MODE": "true"
},
"secret-envs": {
"GH_TOKEN": "GITHUB_TOKEN"
},
"platforms": [
"linux/amd64",
{
"name": "darwin/amd64",
"runs-on": "macos-latest"
}
]
}
] | | | |
| **`lfs`** | Enable Git LFS. | **false** | **boolean** | `true` |
| | See runs-on field, the following default
| **Output** | **Description** |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`built-images`** | Built images data. |
+| | Candidate entries also contain intended destinations, source and run identity; |
+| | see Candidate builds above. This output does not certify validation success. |
| | Example: |
| | {
"application": {
"name": "application",
"registry": "ghcr.io",
"repository": "my-org/my-repo/application",
"tags": ["pr-63-5222075","pr-63"],
"images": [
"ghcr.io/my-org/my-repo/application:pr-63-5222075@sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d",
"ghcr.io/my-org/my-repo/application:pr-63@sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d"
],
"digest": "sha256:d31aa93410434ac9dcfc9179cac2cb1fd4d7c27f11527addc40299c7c675f49d",
"annotations": {
"org.opencontainers.image.created": "2021-09-30T14:00:00Z",
"org.opencontainers.image.description": "Application image"
},
"platforms": ["linux/amd64", "linux/arm64"]
}
} |
diff --git a/.github/workflows/docker-build-images.yml b/.github/workflows/docker-build-images.yml
index f7332da3..5e387e06 100644
--- a/.github/workflows/docker-build-images.yml
+++ b/.github/workflows/docker-build-images.yml
@@ -2,6 +2,23 @@
# Build images using [Docker build image](../../actions/docker/build-image/README.md).
# This includes [multi-platform](https://docs.docker.com/build/building/multi-platform/) build.
# See [Build caches](../../actions/docker/build-image/README.md#build-caches) for cache behavior and recovery.
+#
+# ## Candidate builds
+#
+# Set `candidate: true` to publish temporary images for validation. Keep the existing
+# image configuration; `images[].tag`, when provided, describes the final tag and
+# OCI version. The workflow generates unique repository/run/attempt-scoped tags
+# and leaves normal PR, branch, release and `latest` tags untouched. Signing and
+# attestations follow the existing inputs. Use digest-qualified `built-images`
+# references in downstream tests.
+#
+# Each candidate entry adds `candidate.destinations` (normal full tagged references),
+# `candidate.source` (`repository` and metadata `revision`) and `candidate.run`
+# (`id` and `attempt` as strings). These describe the build, not successful validation.
+# The workflow does not promote candidates or delete them automatically. Keep
+# production publication gated until a validated promotion mechanism is available.
+# Never delete a registry version that has acquired consumer tags.
+# See [ADR 0005](../../docs/adr/0005-publish-candidates-with-final-image-metadata.md).
---
name: Docker build images
@@ -76,6 +93,14 @@ on: # yamllint disable-line rule:truthy
type: boolean
default: true
required: false
+ candidate:
+ description: |
+ Publish under unique temporary tags while retaining intended OCI metadata.
+ Normal tags are recorded in `built-images` as `candidate.destinations` and
+ are not published. No promotion or automatic cleanup is performed.
+ type: boolean
+ default: false
+ required: false
build-secret-github-app-token-env:
description: |
Environment variable name(s) to pass GitHub token generated by GitHub App.
@@ -161,6 +186,8 @@ on: # yamllint disable-line rule:truthy
built-images:
description: |
Built images data.
+ Candidate entries also contain intended destinations, source and run identity;
+ see Candidate builds above. This output does not certify validation success.
Example:
```json
{
@@ -200,6 +227,7 @@ jobs:
OCI_REGISTRY_PASSWORD: ${{ secrets.oci-registry-password }} # zizmor: ignore[secrets-outside-env]
RUNS_ON_INPUT: ${{ inputs.runs-on }}
IMAGES_INPUT: ${{ inputs.images }}
+ CANDIDATE_INPUT: ${{ inputs.candidate }}
BUILD_SECRET_GITHUB_APP_CLIENT_ID: ${{ inputs.build-secret-github-app-client-id }}
BUILD_SECRET_GITHUB_APP_REPOSITORIES: ${{ inputs.build-secret-github-app-repositories }}
with:
@@ -246,6 +274,10 @@ jobs:
// jscpd:ignore-end
// Check each item
+ if (process.env.CANDIDATE_INPUT === 'true' &&
+ (!images.length || new Set(images.map(image => image?.name)).size !== images.length)) {
+ throw new Error('Candidate builds require a non-empty list with unique image names');
+ }
for (const key in images) {
const image = images[key];
if (typeof image !== 'object') {
@@ -465,6 +497,7 @@ jobs:
repository: ${{ matrix.image.repository }}
image: ${{ matrix.image.name }}
tag: ${{ matrix.image.tag }}
+ candidate: ${{ inputs.candidate }}
context: ${{ matrix.image.context }}
dockerfile: ${{ matrix.image.dockerfile }}
build-args: ${{ matrix.image.build-args }}
diff --git a/actions/docker/build-image/README.md b/actions/docker/build-image/README.md
index e368f64a..717d791c 100644
--- a/actions/docker/build-image/README.md
+++ b/actions/docker/build-image/README.md
@@ -126,9 +126,18 @@ permissions:
# See [Docker get-image-metadata action](../get-image-metadata/README.md).
image: ""
- # Force image tag to publish
+ # Force the intended image tag and OCI version. Candidate mode records this destination without publishing it.
tag: ""
+ # Publish under a unique temporary tag, preserving normal OCI metadata.
+ # Normal tags are returned as `candidate.destinations` in `built-image` without
+ # publishing them. The additional `candidate.source` and `candidate.run` fields
+ # describe the build identity, not successful validation. No promotion or
+ # automatic cleanup is performed. Consume the returned digest reference.
+ #
+ # Default: `false`
+ candidate: "false"
+
# Platform to build for. Example: `linux/amd64`.
# See https://github.com/docker/build-push-action#inputs.
#
@@ -220,7 +229,12 @@ permissions:
| **`image`** | Additional image name. | **false** | - |
| | Example: `application`. | | |
| | See [Docker get-image-metadata action](../get-image-metadata/README.md). | | |
-| **`tag`** | Force image tag to publish | **false** | - |
+| **`tag`** | Force the intended image tag and OCI version. Candidate mode records this destination without publishing it. | **false** | - |
+| **`candidate`** | Publish under a unique temporary tag, preserving normal OCI metadata. | **false** | `false` |
+| | Normal tags are returned as `candidate.destinations` in `built-image` without | | |
+| | publishing them. The additional `candidate.source` and `candidate.run` fields | | |
+| | describe the build identity, not successful validation. No promotion or | | |
+| | automatic cleanup is performed. Consume the returned digest reference. | | |
| **`platform`** | Platform to build for. Example: `linux/amd64`. | **true** | - |
| | See