@starci/hfs 4.12.0 → 4.13.0

package/sync/stack-images.mjs

@@ -17,13 +17,15 @@ const CONTINUE = '\\';
 const NO_IMAGES_MESSAGE = 'no image is declared: declare environments.<env>.deploy (with images) in .starcistacks/application-stacks.yaml before running this workflow';
 const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value); // reason: a YAML mapping
 const hasBuildArgs = (args) => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
+const PLATFORM = /^linux\/(?:amd64|arm64)$/u;
+const DEFAULT_PLATFORMS = ['linux/amd64'];
 function environmentImages(environment) {
     const images = environment?.deploy?.images;
     if (!record(images))
         return [];
     return Object.entries(images)
         .filter(([service, entry]) => NAME.test(service) && record(entry) && NAME.test(String(entry.app)))
-        .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs) }));
+        .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs), sealed: record(entry.buildArgs) && record(entry.buildArgs.sealed) }));
 }
 /**
  * The images of a parsed declaration, [{ service, app, buildArgs }] sorted by service: the union over its environments (the first
@@ -34,7 +36,7 @@ function declaredStackImages(declaration) {
     for (const environment of Object.values(record(declaration?.environments) ? declaration.environments : {})) {
         for (const image of environmentImages(environment)) {
             const known = byService.get(image.service);
-            byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs } : image);
+            byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs, sealed: Boolean(known.sealed || image.sealed) } : image);
         }
     }
     return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
@@ -52,6 +54,16 @@ function imageEnvironments(declaration) {
         .filter(([name, environment]) => NAME.test(name) && environmentImages(environment).length > 0)
         .map(([name, environment]) => [name, environmentImages(environment).map(image => image.app)]));
 }
+/** The environments that carry a deploy block, in declared order, with the auto, approval and platforms keys (defaults: manual, no reviewers, linux/amd64). */
+function deployEnvironments(declaration) {
+    return Object.entries(record(declaration?.environments) ? declaration.environments : {})
+        .filter(([name, environment]) => NAME.test(name) && record(environment?.deploy))
+        .map(([name, environment]) => {
+        const deploy = environment.deploy;
+        const platforms = Array.isArray(deploy.platforms) ? deploy.platforms.filter((value) => typeof value === 'string' && PLATFORM.test(value)) : [];
+        return { name, auto: deploy.auto === true, approval: deploy.approval === 'reviewers' ? 'reviewers' : 'none', platforms: platforms.length ? platforms : DEFAULT_PLATFORMS };
+    });
+}
 /**
  * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
  * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
@@ -71,78 +83,227 @@ export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
 }
 /** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
 export function declaredStack(declaration) {
-    return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
+    const cache = declaration?.ci?.imageCache;
+    return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration), environments: deployEnvironments(declaration), imageCache: cache === 'registry' ? 'registry' : 'gha' };
 }
 const envName = (service) => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
 /** Lines placed at the end of a template line: each one starts with a newline, so nothing declared leaves nothing, not even a blank line. */
 const block = (items, indent = INDENT) => items.map(item => `\n${indent}${item}`).join('');
-function buildArgsStep(image) {
-    return [
-        `- name: public build values of ${image.service}`,
-        `  id: args-${image.service}`,
-        '  env:',
-        '    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}',
-        `  run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app ${image.app}`,
-    ];
+/** Lines of a block placed on a line of their own, each indented (an empty list is the empty string). */
+const lines = (items, indent) => items.map(item => (item === '' ? '' : `${indent}${item}`)).join('\n');
+const CHECKOUT = 'actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0';
+const SETUP_NODE = 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0';
+const SETUP_BUILDX = 'docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0';
+const SETUP_QEMU = 'docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0';
+const DOCKER_LOGIN = 'docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0';
+const BUILD_PUSH = 'docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2';
+const INSTALL_SOPS = 'mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0';
+const TAG_MATCHES_VERSION = 'node -e "const version=require(\'./package.json\').version;if(process.env.GITHUB_REF_NAME!==\'v\'+version)process.exit(1)"';
+/**
+ * Which of the app's images need build values, and from where. The values of the release environment (the sole image environment, or production
+ * when several deploy images) are the ones an image is built with; an app that environment does not deploy keeps its Dockerfile defaults.
+ */
+function imagePlans(apps, { images, imageEnvironments: environments = {} }) {
+    const selected = new Set(environments[releaseEnvironment(environments)] ?? []);
+    return apps.map((app) => {
+        const own = images.filter(image => image.app === app.name);
+        const args = selected.has(app.name) && own.some(image => image.buildArgs);
+        return { ...app, deployed: own.length > 0, args, sealed: args && own.some(image => image.sealed === true), services: own.map(image => image.service) };
+    });
+}
+const matrixEntries = (plans) => plans.flatMap(plan => [`- name: ${plan.name}`, `  file: ${plan.file}`, `  deployed: ${plan.deployed}`, `  args: ${plan.args}`]);
+/** The platforms every deploying environment needs, the union in a stable order (default linux/amd64: the VPS's architecture). */
+function platformsOf(environments) {
+    const all = new Set(environments.flatMap(environment => environment.platforms));
+    return all.size ? [...all].sort(byCodeUnit) : DEFAULT_PLATFORMS;
+}
+function imageCacheLines(cache) {
+    if (cache === 'registry')
+        return [
+            'cache-from: type=registry,ref=${{ steps.names.outputs.repo }}:buildcache',
+            "cache-to: ${{ inputs.push && format('type=registry,ref={0}:buildcache,mode=max', steps.names.outputs.repo) || '' }}",
+        ];
+    return ['cache-from: type=gha,scope=${{ matrix.name }}', 'cache-to: type=gha,scope=${{ matrix.name }},mode=max'];
 }
-function buildPushStep(image, dockerfile) {
-    return [
-        `- name: build and push ${image.service}`,
-        `  id: build-${image.service}`,
-        '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
+/** One build job of images.yml: `image` builds with public values and no environment, `image-sealed` opens the sealed build values of the release environment. */
+function imageJob(id, plans, { project, nodeMajor, environment, platforms, cache }) {
+    const sealed = id === 'image-sealed';
+    const qemu = platforms.some(platform => platform !== 'linux/amd64');
+    const head = [
+        `${id}:`,
+        '  timeout-minutes: 30',
+        '  runs-on: ubuntu-latest',
+        ...(sealed ? ['  if: ${{ inputs.release }}', `  environment: ${environment}`] : []),
+        '  permissions:', '    contents: read', '    packages: write',
+        '  strategy:', '    fail-fast: false', '    matrix:', '      include:',
+        ...matrixEntries(plans).map(line => `        ${line}`),
+        '  steps:',
+    ];
+    const steps = [
+        `- uses: ${CHECKOUT}`,
+        '- name: release tag matches package version',
+        '  if: ${{ inputs.release }}',
+        '  shell: bash',
+        '  run: |',
+        '    [[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1',
+        `    ${TAG_MATCHES_VERSION}`,
+        '- name: image repository',
+        '  id: names',
+        '  shell: bash',
+        '  run: |',
+        '    owner="${GITHUB_REPOSITORY_OWNER,,}"',
+        `    echo "repo=ghcr.io/\${owner}/${project}-\${{ matrix.name }}" >> "$GITHUB_OUTPUT"`,
+        ...(qemu ? [`- uses: ${SETUP_QEMU}`] : []),
+        `- uses: ${SETUP_BUILDX}`,
+        `- uses: ${DOCKER_LOGIN}`,
+        '  if: ${{ inputs.push }}',
+        '  with:', '    registry: ghcr.io', '    username: ${{ github.actor }}', '    password: ${{ github.token }}',
+        `- uses: ${SETUP_NODE}`,
+        '  if: ${{ matrix.args }}',
+        '  with:', `    node-version: ${nodeMajor}`, '    cache: npm',
+        '- run: npm ci --ignore-scripts',
+        '  if: ${{ matrix.args }}',
+        ...(sealed ? ['- name: install SOPS', '  if: ${{ matrix.args }}', `  uses: ${INSTALL_SOPS}`, '  with:', '    version: v3.13.2'] : []),
+        '- name: public build values',
+        '  id: args',
+        '  if: ${{ matrix.args }}',
+        '  env:',
+        ...(sealed ? ['    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}'] : []),
+        '    IMAGE_APP: ${{ matrix.name }}',
+        `  run: npx --no-install starci app stack build-args --env ${environment} --app "$IMAGE_APP"`,
+        `- uses: ${BUILD_PUSH}`,
         '  with:',
         '    context: .',
-        `    file: ${dockerfile}`,
-        '    push: true',
-        '    provenance: false',
-        `    tags: \${{ steps.names.outputs.${image.service} }}:\${{ github.sha }}`,
-        ...(image.buildArgs ? [`    build-args: \${{ steps.args-${image.service}.outputs.args }}`] : []),
-        `    cache-from: type=gha,scope=${image.service}`,
-        `    cache-to: type=gha,scope=${image.service},mode=max`,
+        '    file: ${{ matrix.file }}',
+        '    build-args: ${{ steps.args.outputs.args }}',
+        `    platforms: ${platforms.join(',')}`,
+        '    push: ${{ inputs.push && matrix.deployed }}',
+        // Immutable and per commit; the release name v<version> is added below without a rebuild, so the digest the checks proved is the one that ships.
+        '    tags: ${{ steps.names.outputs.repo }}:sha-${{ github.sha }}',
+        // The SBOM and the provenance are attached to the pushed digest (OCI attestations); a build that is not pushed is only a proof that the Dockerfile builds.
+        '    sbom: true',
+        '    provenance: mode=max',
+        ...imageCacheLines(cache).map(line => `    ${line}`),
+        '- name: tag the release',
+        '  if: ${{ inputs.release && inputs.push && matrix.deployed }}',
+        '  shell: bash',
+        '  env:',
+        '    REPO: ${{ steps.names.outputs.repo }}',
+        '  run: docker buildx imagetools create --tag "$REPO:$GITHUB_REF_NAME" "$REPO:sha-$GITHUB_SHA"',
     ];
+    return lines([...head, ...steps.map(step => `    ${step}`)], '  ');
+}
+/** The collect job: the digests this run pushed under sha-<sha>, as the JSON the deploy takes. The images of sealed build values exist only on a release run. */
+function collectJob(plans, jobs, project) {
+    const waits = jobs.map(job => (job === 'image' ? "needs.image.result == 'success'" : "(needs.image-sealed.result == 'success' || needs.image-sealed.result == 'skipped')"));
+    const list = plans.filter(plan => plan.deployed).flatMap(plan => plan.services.map(service => `${service} ${plan.name} ${plan.sealed}`));
+    return lines([
+        'collect:',
+        `  needs: [${jobs.join(', ')}]`,
+        `  if: \${{ !cancelled() && inputs.push && ${waits.join(' && ')} }}`,
+        '  timeout-minutes: 10',
+        '  runs-on: ubuntu-latest',
+        '  permissions:', '    contents: read', '    packages: read',
+        '  outputs:', '    refs: ${{ steps.refs.outputs.refs }}',
+        '  steps:',
+        `    - uses: ${SETUP_BUILDX}`,
+        `    - uses: ${DOCKER_LOGIN}`,
+        '      with:', '        registry: ghcr.io', '        username: ${{ github.actor }}', '        password: ${{ github.token }}',
+        '    - name: pushed digests',
+        '      id: refs',
+        '      shell: bash',
+        '      env:', '        RELEASE: ${{ inputs.release }}',
+        '      run: |',
+        '        set -euo pipefail',
+        '        owner="${GITHUB_REPOSITORY_OWNER,,}"',
+        "        refs='{}'",
+        '        while read -r service app sealed; do',
+        '          if [[ "$sealed" == true && "$RELEASE" != true ]]; then continue; fi',
+        `          repo="ghcr.io/\${owner}/${project}-\${app}"`,
+        "          digest=$(docker buildx imagetools inspect \"$repo:sha-$GITHUB_SHA\" --format '{{json .Manifest}}' | jq -r .digest)",
+        '          [[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo "::error::no pushed digest for the image of ${service}"; exit 1; }',
+        "          refs=$(jq -c --arg service \"$service\" --arg ref \"$repo@$digest\" '. + {($service): $ref}' <<<\"$refs\")",
+        "        done <<'LIST'",
+        ...list.map(entry => `        ${entry}`),
+        '        LIST',
+        '        echo "refs=$refs" >> "$GITHUB_OUTPUT"',
+    ], '  ');
 }
 /**
- * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
- * a newline; empty when there is nothing to place):
- *   stackGuard       the first step of the release job when the app declares no image (it fails with the reason)
- *   stackNames       the `names` step lines assigning each image repository (ghcr.io/<lowercase owner>/<project>-<app>)
- *   stackImageSteps  per image: the optional build-args step and the build-and-push step
- *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest
+ * The text blocks of images.yml, the reusable workflow ci.yml calls. imageJobs holds the build jobs (public values; sealed values bound to the
+ * release environment, release runs only) and the collect job when an image is deployed; imageWorkflowOutputs the `refs` output of the call.
+ */
+function imageWorkflowVariables(stack, project, apps, nodeMajor, environment) {
+    const plans = imagePlans(apps, stack);
+    const publicPlans = plans.filter(plan => !plan.sealed);
+    const sealedPlans = plans.filter(plan => plan.sealed);
+    const options = { project, nodeMajor, environment, platforms: platformsOf(stack.environments ?? []), cache: stack.imageCache ?? 'gha' };
+    const jobs = [...(publicPlans.length ? ['image'] : []), ...(sealedPlans.length ? ['image-sealed'] : [])];
+    const collect = plans.some(plan => plan.deployed) && jobs.length > 0;
+    return {
+        imageJobs: [
+            ...(publicPlans.length ? [imageJob('image', publicPlans, options)] : []),
+            ...(sealedPlans.length ? [imageJob('image-sealed', sealedPlans, options)] : []),
+            ...(collect ? [collectJob(plans, jobs, project)] : []),
+        ].join('\n\n'),
+        imageWorkflowOutputs: collect ? lines(['outputs:', '  refs:', '    description: JSON object, service -> repository@sha256:digest of the images this run pushed', '    value: ${{ jobs.collect.outputs.refs }}'], '    ') : '',
+        imagesCollected: collect ? 'true' : '',
+    };
+}
+/** The deploy jobs of ci.yml: one call of the reusable stack-deploy.yml per environment with deploy.auto, in declared order, each after the one before it. */
+function ciDeployVariables(stack, collected) {
+    const auto = (stack.environments ?? []).filter(environment => environment.auto);
+    const jobs = auto.map((environment, index) => {
+        const previous = index > 0 ? `, deploy-${auto[index - 1].name}` : '';
+        return lines([
+            `deploy-${environment.name}:`,
+            `  needs: [plan, verdict${collected ? ', images' : ''}${previous}]`,
+            "  if: ${{ needs.plan.outputs.release == 'true' }}",
+            '  permissions:', '    contents: read', '    packages: read', '    actions: read',
+            '  concurrency:', `    group: deploy-${environment.name}`, '    cancel-in-progress: false',
+            '  uses: ./.github/workflows/stack-deploy.yml',
+            '  with:',
+            `    environment: ${environment.name}`,
+            '    operation: deploy',
+            '    auto: true',
+            ...(collected ? ['    images: ${{ needs.images.outputs.refs }}'] : []),
+            '    ci_run: ${{ needs.plan.outputs.ci_run }}',
+        ], '  ');
+    });
+    return { ciDeployJobs: jobs.length ? `\n${jobs.join('\n\n')}\n` : '' };
+}
+/** The release environment: the sole image environment, or production when several deploy images. */
+function releaseEnvironment(environments) {
+    const names = Object.keys(environments);
+    return names.length > 1 ? 'production' : names[0] ?? 'production';
+}
+/**
+ * The text blocks the managed workflows place at the end of a line or on a line of their own (empty when there is nothing to place):
+ *   stackGuard       the first step of the deploy job when the app declares no image (it fails with the reason)
+ *   stackImageList   the `<service> <app>` lines the image step of stack-deploy.yml reads (the registry holds sha-<sha> of each)
+ *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest, from the image step
  *   stackImageArgs   the `--image "<service>=$IMAGE_<SERVICE>" \` continuation lines of the deploy command
  *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
- * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
+ *   imageJobs, imageWorkflowOutputs   the build and collect jobs and the output of images.yml
+ *   ciDeployJobs     the deploy jobs of ci.yml (one per environment with deploy.auto)
+ * `apps` are the apps images.yml builds, each with its Dockerfile (the sync module knows the layout).
  */
-export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {} }, project, dockerfileOf) {
+export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {}, environments: deploying = [], imageCache = 'gha' }, project, apps = [], nodeMajor = '22') {
     const guard = images.length ? '' : block([
         '- name: require a declared image',
         '  shell: bash',
         `  run: 'echo "::error::${NO_IMAGES_MESSAGE}"; exit 1'`,
     ]);
-    const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
+    const stack = { images, passEnv, imageEnvironments: environments, environments: deploying, imageCache };
+    const image = imageWorkflowVariables(stack, project, apps, nodeMajor, releaseEnvironment(environments));
     return {
-        ...releaseImageVariables(environments),
+        imageEnvironment: releaseEnvironment(environments),
+        ...image,
+        ...ciDeployVariables(stack, image.imagesCollected === 'true'),
         stackGuard: guard,
-        stackNames: block(names, ' '.repeat(10)),
-        stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
-        stackImageEnv: block(images.map(image => `${envName(image.service)}: \${{ steps.names.outputs.${image.service} }}@\${{ steps.build-${image.service}.outputs.digest }}`), ' '.repeat(10)),
-        stackImageArgs: block(images.map(image => `--image "${image.service}=$${envName(image.service)}" ${CONTINUE}`), ' '.repeat(12)),
+        stackImageList: images.map(entry => `${entry.service} ${entry.app}`).join('\n          '),
+        stackImageEnv: block(images.map(entry => `${envName(entry.service)}: \${{ steps.images.outputs.${entry.service} }}`), ' '.repeat(10)),
+        stackImageArgs: block(images.map(entry => `--image "${entry.service}=$${envName(entry.service)}" ${CONTINUE}`), ' '.repeat(12)),
         stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
     };
 }
-/** The matrix uses the deploy verb only for apps the selected environment deploys; undeployed images retain Dockerfile defaults. */
-function releaseImageVariables(environments) {
-    const names = Object.keys(environments);
-    const selectedApp = names.map(name => `(env.STACK_ENVIRONMENT == '${name}' && contains(fromJSON('${JSON.stringify(environments[name])}'), matrix.name))`).join(' || ') || 'false';
-    const multiple = names.length > 1;
-    const environment = multiple ? 'production' : names[0] ?? 'production';
-    return {
-        imageEnvironment: environment,
-        imageJobEnvironment: names.length ? `\n    environment: ${environment}` : '',
-        imageEnvironmentGuard: multiple ? block([
-            '- name: require a declared image environment',
-            `  if: \${{ !contains(fromJSON('${JSON.stringify(names)}'), env.STACK_ENVIRONMENT) }}`,
-            '  run: \'echo "::error::STACKS_DEPLOY_ENV_UNKNOWN: selected environment declares no deploy images"; exit 1\'',
-        ]) : '',
-        imageBuildArgsIf: `\${{ ${selectedApp} }}`,
-    };
-}

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -1,25 +1,85 @@
 {{header}}
 name: ci
 
-# CI judges main, release candidates and release tags.
+# CI judges pull requests, main, release candidates and release tags, and a green release tag deploys.
+#   pull_request  the checks and the image builds of a change to main, with no secret and no environment (a Dependabot or fork run has none anyway);
+#                 and no run of this workflow executes a pull request's code with a token that can write
+#   main          judged only when no release tag points at the pushed commit (the release push sends main and its tag together; the tag run is the release run)
+#   candidate     release/candidate-<version>: the full run of a release the tag run then reuses
+#   tag v*        the release run: plan, checks and images in parallel, the verdict, then the deploy of every environment with deploy.auto
 on:
   push:
     branches: ["main", "release/candidate-*"]
     tags: ["v*"]
+  pull_request:
+    branches: ["main"]
   workflow_dispatch:
 
 permissions:
   contents: read
 
-# One run per ref: a release tag is never cancelled by another run.
+# The committed check cache (.starcistacks/cache, contexts/project/check-cache.md): a run judges only what differs from the cache at its trusted base
+# (the first parent of a push to main). A release candidate and a release tag judge in full and never read the cache.
+env:
+  STARCI_APP_CHECK_CACHE: ${{ (startsWith(github.ref, 'refs/tags/') || startsWith(github.ref, 'refs/heads/release/candidate-')) && 'full' || '' }}
+
+# One run per ref. A pull request run is replaced by the next push to it; every other run, a release tag above all, is never cancelled.
 concurrency:
   group: ci-${{ github.ref }}
-  cancel-in-progress: false
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
-# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): fast, lint per side, the unit run in shards, one coverage merge, build,
-# and sonar. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
+# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): plan, fast, lint per side, the unit run in shards, one coverage merge, build, images,
+# sonar, the verdict and the deploy jobs. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
+# A job the plan leaves out is never a green one: the verdict job requires every job it needs to be green or, where the plan left it out on purpose, not run.
 jobs:
+  plan:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      checks: ${{ steps.plan.outputs.checks }}
+      images: ${{ steps.plan.outputs.images }}
+      push: ${{ steps.plan.outputs.push }}
+      full: ${{ steps.plan.outputs.full }}
+      release: ${{ steps.plan.outputs.release }}
+      ci_run: ${{ steps.plan.outputs.ci_run }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+      - name: plan
+        id: plan
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT: ${{ github.event_name }}
+          REF_TYPE: ${{ github.ref_type }}
+        run: |
+          set -euo pipefail
+          checks=true images=true push=false full=false release=false ci_run="$GITHUB_RUN_ID" note="checks and image builds"
+          if [[ "$EVENT" == push ]]; then
+            full=true push=true
+            if [[ "$REF_TYPE" == tag ]]; then
+              release=true
+              [[ "$GITHUB_REF_NAME" == "v$(node -p "require('./package.json').version")" ]] || { echo "::error::the release tag does not match the package version"; exit 1; }
+              reused=$(gh api "repos/${GITHUB_REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${GITHUB_SHA}&event=push&status=success&per_page=100" --jq '[.workflow_runs[] | select(.head_branch | startswith("release/candidate-"))] | first | .id // empty')
+              if [[ -n "$reused" ]]; then checks=false ci_run="$reused" note="release run: the green candidate run $reused judged this commit; images are built and pushed here"; else note="release run: full checks and images"; fi
+            elif [[ "$GITHUB_REF" == refs/heads/release/candidate-* ]]; then
+              note="candidate run: full checks; images are built and pushed under sha-<sha>"
+            elif [[ -n "$(git tag --points-at "$GITHUB_SHA" --list 'v*')" ]]; then
+              checks=false images=false push=false full=false note="deferred: the release tag run of this commit judges it"
+            else
+              images=false push=false full=false note="main without a release tag: checks only"
+            fi
+          fi
+          { echo "checks=$checks"; echo "images=$images"; echo "push=$push"; echo "full=$full"; echo "release=$release"; echo "ci_run=$ci_run"; } >> "$GITHUB_OUTPUT"
+          echo "plan: $note" >> "$GITHUB_STEP_SUMMARY"
+
   fast:
+    needs: plan
+    if: ${{ needs.plan.outputs.checks == 'true' }}
     timeout-minutes: {{timeoutFast}}
     runs-on: ubuntu-latest
     steps:
@@ -27,13 +87,15 @@ jobs:
       - name: production dependency audit
         run: {{auditCommand}}
       - name: format
-        run: npm run format:check
+        run: npx --no-install starci app check --format
       - name: typecheck
         run: npm run typecheck
         env:
           NODE_OPTIONS: {{nodeOptions}}
 
   lint:
+    needs: plan
+    if: ${{ needs.plan.outputs.checks == 'true' }}
     timeout-minutes: {{timeoutLint}}
     runs-on: ubuntu-latest
     strategy:
@@ -46,6 +108,8 @@ jobs:
 {{ciLintSteps}}
 
   test:
+    needs: plan
+    if: ${{ needs.plan.outputs.checks == 'true' }}
     timeout-minutes: {{timeoutTest}}
     runs-on: ubuntu-latest
     strategy:
@@ -69,7 +133,7 @@ jobs:
           path: {{shardCoverageReport}}
 
   coverage:
-    needs: test
+    needs: [plan, test]
     timeout-minutes: {{timeoutCoverage}}
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
@@ -96,6 +160,8 @@ jobs:
 {{codecovSteps}}
 
   build:
+    needs: plan
+    if: ${{ needs.plan.outputs.checks == 'true' }}
     timeout-minutes: {{timeoutBuild}}
     runs-on: ubuntu-latest
     steps:
@@ -106,3 +172,44 @@ jobs:
 {{> app/ci-workflows/build-cache-save.yml}}
 
 {{sonarJob}}
+  images:
+    needs: plan
+    if: ${{ needs.plan.outputs.images == 'true' }}
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/images.yml
+    with:
+      push: ${{ needs.plan.outputs.push == 'true' }}
+      release: ${{ needs.plan.outputs.release == 'true' }}
+
+  verdict:
+    needs: [plan, fast, lint, test, coverage, build, images{{verdictSonarNeed}}]
+    if: ${{ always() }}
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: verdict
+        shell: bash
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+          CHECKS: ${{ needs.plan.outputs.checks }}
+          IMAGES: ${{ needs.plan.outputs.images }}
+          FULL: ${{ needs.plan.outputs.full }}
+        run: |
+          set -euo pipefail
+          fail=0
+          expect() {
+            got=$(jq -r --arg job "$1" '.[$job].result' <<<"$NEEDS")
+            case "$2" in
+              success) [[ "$got" == success ]] || { echo "::error::job $1 is $got, expected success"; fail=1; } ;;
+              idle) [[ "$got" != success && "$got" != failure && "$got" != cancelled ]] || { echo "::error::job $1 ran ($got) where the plan left it out"; fail=1; } ;;
+            esac
+          }
+          expect plan success
+          if [[ "$CHECKS" == true ]]; then want=success; else want=idle; fi
+          for job in fast lint test coverage build; do expect "$job" "$want"; done
+          if [[ "$IMAGES" == true ]]; then expect images success; else expect images idle; fi{{verdictSonarCheck}}
+          exit "$fail"
+{{ciDeployJobs}}

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -1,74 +1,30 @@
 {{header}}
-# Builds the image of every app on its release tag, so a Dockerfile that no longer builds fails that release.
-# It never pushes: publishing an image is the product's decision, not this file's.
-# When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
-# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key --env <env> --backup github --execute).
+# Builds every image the app declares, once per commit, and pushes the deployed ones to GHCR. ci.yml calls it next to the checks, so the images
+# are built in parallel with them and a Dockerfile that no longer builds fails the same run. It has no trigger of its own.
+#   tags       sha-<sha> on every push; the release tag v<version> is added on a release run by retagging that digest (no rebuild), so the
+#              image the checks ran beside is the image that ships. No mutable environment tag is ever written or deployed.
+#   evidence   an SBOM and provenance (mode=max) are attached to the pushed digest; a build that is not pushed only proves the Dockerfile builds.
+#   values     build arguments are public values (the browser receives them); a secret never enters an image build.
+#   sealed     an image whose public build values live in a sealed member is built by the job bound to the release environment, on a release
+#              tag run only (that environment is restricted to v* tags); every other image builds without an environment or a secret.
+# The workflow is read by anyone when the repository is public: it runs on GitHub-hosted runners only, and nothing it prints names a host.
 name: images
 
 on:
-  push:
-    tags: ["v*"]
+  workflow_call:
+    inputs:
+      push:
+        description: Push the deployed images (a push run); a pull request or a manual run only builds them
+        required: true
+        type: boolean
+      release:
+        description: A release tag run - also tag the pushed images v<version> and build the images that open sealed build values
+        required: true
+        type: boolean
+{{imageWorkflowOutputs}}
 
 permissions:
   contents: read
 
-# One run per ref.
-concurrency:
-  group: images-${{ github.ref }}
-  cancel-in-progress: false
-
 jobs:
-  image:
-    timeout-minutes: 30
-    runs-on: ubuntu-latest{{imageJobEnvironment}}
-    env:
-      STACK_ENVIRONMENT: {{imageEnvironment}}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-{{imageMatrix}}
-    steps:{{imageEnvironmentGuard}}
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      - name: release tag matches package version
-        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        if: {{imageBuildArgsIf}}
-        with:
-          node-version: {{nodeMajor}}
-          cache: npm
-      - run: npm ci --ignore-scripts
-        if: {{imageBuildArgsIf}}
-      - name: install SOPS
-        if: {{imageBuildArgsIf}}
-        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
-        with:
-          version: v3.13.2
-      - name: public build values
-        id: args
-        if: {{imageBuildArgsIf}}
-        env:
-          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
-          IMAGE_APP: ${{ matrix.name }}
-        run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app "$IMAGE_APP"
-      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
-      - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
-        with:
-          context: .
-          file: ${{ matrix.file }}
-          build-args: ${{ steps.args.outputs.args }}
-          push: false
-          tags: {{imageProject}}/${{ matrix.name }}:${{ github.ref_name }}
-          # OCI keeps the SBOM and provenance attestations without publishing to a registry.
-          outputs: type=oci,dest=${{ runner.temp }}/${{ matrix.name }}.oci.tar
-          sbom: true
-          provenance: mode=max
-          cache-from: type=gha,scope=${{ matrix.name }}
-          cache-to: type=gha,scope=${{ matrix.name }},mode=max
-      - name: retain image with SBOM and provenance
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: image-${{ matrix.name }}-${{ github.sha }}-${{ github.run_attempt }}
-          path: ${{ runner.temp }}/${{ matrix.name }}.oci.tar
-          if-no-files-found: error
-          compression-level: 0
+{{imageJobs}}