diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 7b7d4a6f..c54fd10e 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -348,7 +348,12 @@ generate:ci-workflow`. The contract allows the steps `checkout`, `setup-node`, `frozen-install`, `download` (the `promoted-release` transfer), `extract`, and one final `deploy` step whose `script` names a package script. Its variables may only be the `CANDIDATE_ARCHIVE_SHA256` digest of `immutable_build` and -`vars.*` or `secrets.*` values. The `deploy` step writes `deployed=true` only +`vars.*` or `secrets.*` values. A slot with a deploy script must download only +the `promoted-release` transfer, extract its `release-candidate.tar.gz` and +bind the digest, so the script deploys the promoted candidate rather than a +rebuild (1103/13-01). `secrets.*` values are rendered on the `deploy` step +alone, not on the job, so checkout, setup-node and the download action never +see them (1103/13-05). The `deploy` step writes `deployed=true` only after the script succeeds. The job owns no gate, so filling it changes neither gate ownership nor the contract baseline. Browser boot, live API traffic, smoke after a provider switch, and anything the runbook marks as needing provider verification are diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index 066250b3..aa53ef0d 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -1027,6 +1027,7 @@ function validateContractSemantics( if (duplicate || foreign.length > 0) { issue(`deployment slot binding must be the candidate digest or a vars.* or secrets.* value: ${job.id}`); } + for (const failure of deploymentSlotInputFailures(job)) issue(failure); } else if (duplicate || JSON.stringify(job.environment) !== JSON.stringify(expectedEnvironmentBindings[job.id])) { issue(`job environment binding drift: ${job.id}`); } @@ -1244,6 +1245,47 @@ function validateCanonicalStepFields( } } +/** + * 1103/13-01. A slot that runs a deploy script deploys the promoted candidate: + * it downloads the promoted-release transfer and extracts its + * release-candidate.tar.gz, checked against the digest immutable_build + * recorded, before the script runs. A slot that rebuilt instead passed the + * contract under the name deploy-promoted-release, and FE-GATE-019 could not + * tell the rebuild from the candidate. + */ +function deploymentSlotInputFailures(job: z.infer): string[] { + const deploy = job.steps.find((step) => step.kind === "deploy"); + if (deploy?.kind !== "deploy" || deploy.script === undefined) return []; + const failures: string[] = []; + const downloads = job.steps.filter((step) => step.kind === "download"); + const download = downloads[0]; + const extract = job.steps.find((step) => step.kind === "extract"); + if ( + downloads.length !== 1 || + download?.kind !== "download" || + download.transferId !== "promoted-release" || + extract?.kind !== "extract" || + extract.archivePath !== `${download.path}/release-candidate.tar.gz` || + job.steps.indexOf(download) > job.steps.indexOf(extract) + ) { + failures.push( + `deployment slot with a deploy script must download only the promoted-release transfer and extract its release-candidate.tar.gz before deploying: ${job.id}`, + ); + } + if ( + !job.environment.some( + ({ name, value }) => + name === "CANDIDATE_ARCHIVE_SHA256" && + value === "${{ needs.immutable_build.outputs.archive_sha256 }}", + ) + ) { + failures.push( + `deployment slot with a deploy script must bind CANDIDATE_ARCHIVE_SHA256 so its extract step checks the promoted archive: ${job.id}`, + ); + } + return failures; +} + function validateJobStepKinds( job: z.infer, issue: (message: string, path?: PropertyKey[]) => void, diff --git a/scripts/generate-ci-workflow.ts b/scripts/generate-ci-workflow.ts index b37d8b58..81db43cd 100644 --- a/scripts/generate-ci-workflow.ts +++ b/scripts/generate-ci-workflow.ts @@ -144,9 +144,10 @@ function renderJob( if (job.kind === "deployment") { lines.push(" outputs:", " deployed: ${{ steps.deploy.outputs.deployed }}"); } - if (job.environment.length > 0) { + const jobEnvironment = job.environment.filter((binding) => !isStepScopedSecret(job, binding)); + if (jobEnvironment.length > 0) { lines.push(" env:"); - for (const binding of job.environment) { + for (const binding of jobEnvironment) { lines.push(` ${binding.name}: ${yamlScalar(binding.value)}`); } } @@ -276,11 +277,15 @@ function renderStep( ]; // 1101/13-01. `run` fails on the first failing command, so deployed=true // is written only after the project's script succeeded. - case "deploy": + case "deploy": { + const secrets = job.environment.filter((binding) => isStepScopedSecret(job, binding)); return step.script ? [ " - name: Deploy the promoted release", " id: deploy", + ...(secrets.length > 0 + ? [" env:", ...secrets.map((binding) => ` ${binding.name}: ${yamlScalar(binding.value)}`)] + : []), " run: |", // The contract limits the name to [A-Za-z0-9:_-], a plain shell word. ` corepack pnpm ${step.script}`, @@ -291,6 +296,7 @@ function renderStep( " id: deploy", ' run: echo "deployed=false" >> "$GITHUB_OUTPUT"', ]; + } case "upload": { const lines = [ ` - name: Upload ${humanize(step.transferId)}`, @@ -310,6 +316,16 @@ function renderStep( } } +/** + * 1103/13-05. Job env reaches every step of the job: checkout, setup-node and + * the third-party download action as well. In the deployment slot a + * `secrets.*` binding is rendered on the deploy step instead, the one step + * that uses it. + */ +function isStepScopedSecret(job: CiWorkflowJob, binding: CiWorkflowJob["environment"][number]): boolean { + return job.kind === "deployment" && /^\$\{\{ secrets\./u.test(binding.value); +} + function requiredStepActionUses(stepKind: string): string { const uses = resolveCiStepActionUses(stepKind); if (!uses) throw new TypeError(`workflow step has no registered CI action: ${stepKind}`); diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts index 1fa8fb94..ea0d5866 100644 --- a/tests/unit/ci-workflow-generation.test.ts +++ b/tests/unit/ci-workflow-generation.test.ts @@ -386,7 +386,14 @@ describe("CI gate contract", () => { ); const workflow = renderCiWorkflow(contract); const job = workflow.slice(workflow.indexOf(" deployment:\n"), workflow.indexOf(" production_gate:\n")); - expect(job).toContain('DEPLOY_SSH_KEY: "${{ secrets.DEPLOY_SSH_KEY }}"'); + // 1103/13-05. Job env reaches every step, checkout and the third-party + // download action included; a credential belongs to the deploy step only. + const jobEnvironment = job.slice(job.indexOf(" env:\n"), job.indexOf(" steps:\n")); + const deployStep = job.slice(job.indexOf(" - name: Deploy the promoted release")); + expect(jobEnvironment).toContain('DEPLOY_HOST: "${{ vars.DEPLOY_HOST }}"'); + expect(jobEnvironment).not.toContain("secrets."); + expect(deployStep).toContain(' env:\n DEPLOY_SSH_KEY: "${{ secrets.DEPLOY_SSH_KEY }}"\n'); + expect(job.match(/secrets\./gu)).toHaveLength(1); expect(job.indexOf("--extract-to")).toBeLessThan(job.indexOf("corepack pnpm deploy:release")); expect(job.indexOf("corepack pnpm deploy:release")).toBeLessThan( job.indexOf('echo "deployed=true" >> "$GITHUB_OUTPUT"'), @@ -411,6 +418,18 @@ describe("CI gate contract", () => { (slot: Record) => slot.steps.push({ kind: "checkout" }), /deploy step/u, ], + // 1103/13-01. A slot that rebuilt (or deployed anything but the promoted + // archive) passed the contract under the name deploy-promoted-release. + [ + "a slot that deploys without the promoted candidate", + (slot: Record) => slot.steps.splice(3, 2), + /promoted-release/u, + ], + [ + "a slot that extracts the candidate without its digest", + (slot: Record) => slot.environment.shift(), + /CANDIDATE_ARCHIVE_SHA256/u, + ], ])("rejects %s (1101/13-01)", async (_name, mutate, diagnostic) => { const contract = fillDeploymentSlot( JSON.parse(JSON.stringify(await loadCiGateContract(process.cwd()))),