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 . | | | | +| **`candidate`** | Publish under unique temporary tags while retaining intended OCI metadata. | **false** | **boolean** | `false` | +| | Normal tags are recorded in `built-images` as `candidate.destinations` and | | | | +| | are not published. No promotion or automatic cleanup is performed. | | | | | **`build-secret-github-app-token-env`** | Environment variable name(s) to pass GitHub token generated by GitHub App. | **false** | **string** | `GITHUB_APP_TOKEN` | | | 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. | | | | @@ -344,6 +369,8 @@ If a platform entry omits the 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 . | | | | **`context`** | Build's context is the set of files located in the specified PATH or URL. | **false** | `.` | diff --git a/actions/docker/build-image/action.yml b/actions/docker/build-image/action.yml index c25f2c9e..95e50b02 100644 --- a/actions/docker/build-image/action.yml +++ b/actions/docker/build-image/action.yml @@ -87,7 +87,16 @@ inputs: See [Docker get-image-metadata action](../get-image-metadata/README.md). required: false tag: - description: "Force image tag to publish" + description: "Force the intended image tag and OCI version. Candidate mode records this destination without publishing it." + required: false + candidate: + description: | + 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" required: false platform: description: | @@ -202,6 +211,7 @@ runs: repository: ${{ inputs.repository }} image: ${{ inputs.image }} tag: ${{ inputs.tag }} + candidate: ${{ inputs.candidate }} - id: get-docker-config uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 @@ -437,6 +447,7 @@ runs: METADATA_IMAGE: ${{ steps.metadata.outputs.image }} METADATA_TAGS: ${{ steps.metadata.outputs.tags }} METADATA_ANNOTATIONS: ${{ steps.metadata.outputs.annotations }} + METADATA_CANDIDATE: ${{ steps.metadata.outputs.candidate }} MULTI_PLATFORM: ${{ steps.get-docker-config.outputs.multi-platform }} with: script: | @@ -545,4 +556,8 @@ runs: "multi-platform": isMultiplatform, }; + if (process.env.METADATA_CANDIDATE) { + builtImage.candidate = JSON.parse(process.env.METADATA_CANDIDATE); + } + core.setOutput("built-image", JSON.stringify(builtImage)); diff --git a/actions/docker/get-image-metadata/README.md b/actions/docker/get-image-metadata/README.md index 6a70887c..567c182c 100644 --- a/actions/docker/get-image-metadata/README.md +++ b/actions/docker/get-image-metadata/README.md @@ -50,8 +50,12 @@ It uses the [docker/metadata-action](https://github.com/docker/metadata-action) # Additional image name. Example: `application`. See [Docker get-image-name action](../get-image-name/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: "" + + # Return a temporary publication tag while preserving normal labels, annotations and intended destinations. + # Default: `false` + candidate: "false" ``` @@ -65,7 +69,8 @@ It uses the [docker/metadata-action](https://github.com/docker/metadata-action) | **`oci-registry`** | OCI registry where to pull and push images | **true** | `ghcr.io` | | **`repository`** | Repository name. Example: `my-org/my-repo`. See [Docker get-image-name action](../get-image-name/README.md) | **false** | `${{ github.repository }}` | | **`image`** | Additional image name. Example: `application`. See [Docker get-image-name action](../get-image-name/README.md) | **false** | - | -| **`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`** | Return a temporary publication tag while preserving normal labels, annotations and intended destinations. | **false** | `false` | @@ -76,13 +81,14 @@ It uses the [docker/metadata-action](https://github.com/docker/metadata-action) ## Outputs -| **Output** | **Description** | -| ----------------- | ----------------------------------------------- | -| **`image`** | Forged image name containing registry. | -| | Example: `ghcr.io/my-org/my-repo/application` | -| **`labels`** | The image labels. | -| **`annotations`** | The image annotations. | -| **`tags`** | The image tags. Example: `pr-63-5222075\npr-63` | +| **Output** | **Description** | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`image`** | Forged image name containing registry. | +| | Example: `ghcr.io/my-org/my-repo/application` | +| **`labels`** | The image labels. | +| **`annotations`** | The image annotations. | +| **`tags`** | The image tags. Example: `pr-63-5222075\npr-63` | +| **`candidate`** | JSON describing intended destinations, source and run identity when candidate mode is enabled; empty otherwise. This is not validation evidence. | diff --git a/actions/docker/get-image-metadata/action.yml b/actions/docker/get-image-metadata/action.yml index a425e60f..8e949929 100644 --- a/actions/docker/get-image-metadata/action.yml +++ b/actions/docker/get-image-metadata/action.yml @@ -24,6 +24,9 @@ outputs: tags: description: 'The image tags. Example: `pr-63-5222075\npr-63`' value: ${{ steps.generate-outputs.outputs.tags }} + candidate: + description: "JSON describing intended destinations, source and run identity when candidate mode is enabled; empty otherwise. This is not validation evidence." + value: ${{ steps.generate-outputs.outputs.candidate }} inputs: oci-registry: @@ -38,7 +41,11 @@ inputs: description: "Additional image name. Example: `application`. See [Docker get-image-name action](../get-image-name/README.md)" required: false tag: - description: "Force image tag to publish" + description: "Force the intended image tag and OCI version. Candidate mode records this destination without publishing it." + required: false + candidate: + description: "Return a temporary publication tag while preserving normal labels, annotations and intended destinations." + default: "false" required: false runs: @@ -61,12 +68,16 @@ runs: uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: INPUT_TAG: ${{ inputs.tag }} + INPUT_CANDIDATE: ${{ inputs.candidate }} GH_REF: ${{ github.ref }} DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} ISSUE_NUMBER: ${{ steps.get-issue-number.outputs.issue-number }} with: result-encoding: string script: | + if (!['true', 'false'].includes(process.env.INPUT_CANDIDATE)) { + throw new Error('"candidate" must be true or false'); + } const tagInput = process.env.INPUT_TAG || ""; if (tagInput.length) { core.setOutput('tags',`type=raw,value=${tagInput}`); @@ -126,6 +137,7 @@ runs: DOCKER_METADATA_LABELS: ${{ steps.docker-metadata.outputs.labels }} DOCKER_METADATA_ANNOTATIONS: ${{ steps.docker-metadata.outputs.annotations }} DOCKER_METADATA_TAGS: ${{ steps.docker-metadata.outputs.tags }} + INPUT_CANDIDATE: ${{ inputs.candidate }} with: script: | const image = process.env.IMAGE_NAME_WITH_REGISTRY || ""; @@ -155,4 +167,35 @@ runs: }) .join("\n"); - core.setOutput('tags', sortedTags); + if (process.env.INPUT_CANDIDATE !== 'true') { + core.setOutput('tags', sortedTags); + return; + } + + const repositoryId = process.env.GITHUB_REPOSITORY_ID; + const runId = process.env.GITHUB_RUN_ID; + const attempt = process.env.GITHUB_RUN_ATTEMPT; + if (![repositoryId, runId, attempt].every(value => /^[1-9][0-9]*$/.test(value || ''))) { + throw new Error('Candidate publication requires repository, run and attempt IDs'); + } + const repository = process.env.GITHUB_REPOSITORY; + const revision = labels.match(/^org\.opencontainers\.image\.revision=([a-f0-9]{40})$/m)?.[1]; + if (!repository || !revision) { + throw new Error('Candidate publication requires a source repository and metadata revision'); + } + const destinations = sortedTags.split('\n').filter(Boolean); + if (!destinations.length || destinations.some(tag => !tag.startsWith(`${image}:`))) { + throw new Error('Candidate publication requires destinations in the image repository'); + } + + const { randomUUID } = require('node:crypto'); + const tag = `candidate-${repositoryId}-${runId}-${attempt}-${randomUUID()}`; + if (tag.length > 128 || destinations.includes(`${image}:${tag}`)) { + throw new Error('Invalid candidate publication tag'); + } + core.setOutput('tags', `${image}:${tag}`); + core.setOutput('candidate', JSON.stringify({ + destinations, + source: { repository, revision }, + run: { id: runId, attempt }, + })); diff --git a/docs/README.md b/docs/README.md index 5a583533..cf90971a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,3 +7,4 @@ - [Chart release distribution decision](adr/0002-bundle-chart-release-dependencies.md) - [Publication setup and build digest reuse](adr/0003-reuse-build-digests-and-limit-publication-setup.md) - [Build-cache mount isolation](adr/0004-scope-build-cache-imports-and-mount-snapshots.md) +- [Candidate publication and final image metadata](adr/0005-publish-candidates-with-final-image-metadata.md) diff --git a/docs/adr/0005-publish-candidates-with-final-image-metadata.md b/docs/adr/0005-publish-candidates-with-final-image-metadata.md new file mode 100644 index 00000000..0265b293 --- /dev/null +++ b/docs/adr/0005-publish-candidates-with-final-image-metadata.md @@ -0,0 +1,78 @@ +# ADR 0005: Publish candidates with final image metadata + +Status: Proposed + +Date: 2026-11-12 + +## Context + +Pleey's next CI optimization overlaps production builds with application checks. +Those builds must not move branch, PR, release or `latest` tags before validation. +The existing `tag` override suppresses default tags, but also determines the OCI +version in labels and annotations. Using a temporary tag there would embed the +wrong version in the image that a later promotion must preserve byte for byte. + +Callers should not generate temporary identities or duplicate the workflow's tag +policy. Separate publication from promotion in two reviewable increments. This +record covers candidate publication only; Pleey retains its gated production +ordering until promotion has its own validated contract. + +## Decision + +Add an opt-in `candidate: true` input to the build workflow and its build/metadata +actions. The default retains normal publication. Existing image settings, +including `images[].tag`, describe the intended final metadata and destinations. +Run Docker metadata generation normally, then replace only the publication tags. +Labels and annotations retain the intended version, revision and source. + +Temporary tags contain the calling repository ID, run ID, attempt and a random +UUID. This isolates reruns and repeated invocations without another caller input. +Each platform build generates an identity; a multi-platform build publishes one +candidate tag with the assembled index through the existing manifest action. +Intermediate platform digests remain untagged as they are today. Consumers use +the returned digest-qualified references, never reconstruct a temporary tag. + +The existing `built-images` output keeps its shape. Candidate entries additionally +carry `candidate.destinations` (the normal full tagged references), +`candidate.source` (calling repository and metadata revision), and `candidate.run` +(run ID and attempt as strings). The existing digest identifies the built image +or assembled index. This data describes a build; it is not proof that validation +passed or permission to promote it. Signing and attestation settings retain their +existing behavior and permissions. + +This refines Pleey ADR 0023's proposal to supply temporary tags through +`images[].tag`: that field keeps its final-version meaning, while the opt-in mode +owns temporary naming. No raw metadata or destination configuration is added. + +## Consequences and boundaries + +- Candidate mode performs registry writes, including configured signatures and + attestations. It changes no normal image tags. It is not a local-only build. +- The random suffix avoids collisions across independent calls in the same run. + Reruns create new candidates; old outputs remain tied to their original attempt. +- Images retain final OCI metadata, so later same-repository digest promotion can + avoid rebuilding or rewriting manifests. This increment does not implement it. +- No automatic candidate deletion is added. Deleting a registry version by digest + could delete subsequently promoted content and its evidence. Retention needs a + registry-specific policy that preserves referenced content. +- The promotion increment must bind successful validation to these digests, + authorize destinations, reject stale/superseded runs, serialize conflicting + writers, preserve signatures/provenance and define partial-write recovery. + Workflow concurrency alone does not establish atomic multi-tag publication. +- Pleey must not relax production dependencies or adopt candidate mode before + that promotion contract and its validation gate are reviewed and tested. + +## Validation + +Required checks: unchanged default metadata; candidate PR/default-branch/release +destinations; forced final tags; isolated run/attempt/call identities; malformed +identity rejection; single- and multi-platform publication using the existing +test Dockerfile; preserved OCI version and digest outputs; absent final tags; +signatures and provenance; failed build without a successful candidate output. +Validation results will be recorded with the implementation PR. + +## References + +- [Pleey optimization plan](https://github.com/cloud-native-aixmarseille/pleey/blob/ci/475-p1-local-reductions/docs/technical/plans/0023-optimize-ci-execution-and-caching.md#p25-candidate-publication-and-exact-digest-promotion) +- [Docker metadata tag priority and image version](https://github.com/docker/metadata-action#priority-attribute) +- [GitHub run and attempt variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables)