From 09a107bcb8c24e340f0e0fa38ba51d1cf85af2a4 Mon Sep 17 00:00:00 2001 From: echobob Date: Thu, 12 Nov 2026 23:48:26 -0500 Subject: [PATCH 1/3] Share the setup, test, image, Coolify, and PR guard workflows. Callers pin the v1 tag, so one tag move reaches every consumer, and each job still runs on the caller's minutes. Co-authored-by: Cursor --- .github/actions/setup/action.yml | 60 ++++++++++++++ .github/workflows/ci.yml | 24 ++++++ .github/workflows/coolify-deploy.yml | 115 +++++++++++++++++++++++++++ .github/workflows/image.yml | 101 +++++++++++++++++++++++ .github/workflows/pr-guard.yml | 54 +++++++++++++ .github/workflows/setup.yml | 69 ++++++++++++++++ .github/workflows/test.yml | 78 ++++++++++++++++++ README.md | 39 +++++++++ scripts/pr-guard.mjs | 84 +++++++++++++++++++ scripts/pr-guard.test.mjs | 45 +++++++++++ 10 files changed, 669 insertions(+) create mode 100644 .github/actions/setup/action.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/coolify-deploy.yml create mode 100644 .github/workflows/image.yml create mode 100644 .github/workflows/pr-guard.yml create mode 100644 .github/workflows/setup.yml create mode 100644 .github/workflows/test.yml create mode 100644 README.md create mode 100644 scripts/pr-guard.mjs create mode 100644 scripts/pr-guard.test.mjs diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml new file mode 100644 index 0000000..6c37a23 --- /dev/null +++ b/.github/actions/setup/action.yml @@ -0,0 +1,60 @@ +name: setup +description: >- + pnpm, Node, and a frozen install. On macOS the Node architecture is arm64, + so an Apple Silicon runner does not install an x64 binary under Rosetta. + +inputs: + pnpm-version: + description: pnpm version. Match the calling repo's lockfile. + required: false + default: "10.14.0" + node-version: + description: Node version passed to actions/setup-node. + required: false + default: "22" + node-architecture: + description: >- + Node architecture. Empty selects arm64 on macOS and the runner default + everywhere else. + required: false + default: "" + registry-url: + description: Passed to actions/setup-node. Empty writes no registry auth. + required: false + default: "" + github-packages: + description: >- + When true, point pnpm at GitHub Packages with the job token. The caller + job needs packages:read. + required: false + default: "false" + install: + description: Run pnpm install --frozen-lockfile after setup. + required: false + default: "true" + +runs: + using: composite + steps: + - uses: pnpm/action-setup@v4 + with: + version: ${{ inputs.pnpm-version }} + + - uses: actions/setup-node@v4 + with: + node-version: ${{ inputs.node-version }} + architecture: ${{ inputs.node-architecture != '' && inputs.node-architecture || (runner.os == 'macOS' && 'arm64' || '') }} + cache: pnpm + registry-url: ${{ inputs.registry-url }} + + - if: inputs.github-packages == 'true' + name: Authenticate to GitHub Packages + shell: bash + env: + NODE_AUTH_TOKEN: ${{ github.token }} + run: pnpm config set "//npm.pkg.github.com/:_authToken" "$NODE_AUTH_TOKEN" + + - if: inputs.install == 'true' + name: Install + shell: bash + run: pnpm install --frozen-lockfile diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b0212d4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,24 @@ +name: ci + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + guard-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: pr-guard unit tests + run: node --test scripts/pr-guard.test.mjs + + guard: + if: github.event_name == 'pull_request' + uses: ./.github/workflows/pr-guard.yml + with: + require-verification: true + require-refs: true diff --git a/.github/workflows/coolify-deploy.yml b/.github/workflows/coolify-deploy.yml new file mode 100644 index 0000000..b671255 --- /dev/null +++ b/.github/workflows/coolify-deploy.yml @@ -0,0 +1,115 @@ +name: coolify-deploy + +# The job runs in the caller, on the caller's minutes. Secrets are read from +# Infisical with this workflow's GitHub OIDC token. Callers pass the identity +# id and project slug; they do not pass repository secrets. +on: + workflow_call: + inputs: + runner: + description: JSON array of runs-on labels. + required: false + type: string + default: '["ubuntu-latest"]' + infisical-domain: + required: false + type: string + default: https://secrets.practical.works + infisical-identity-id: + description: Infisical machine identity id allowed to assume via GitHub OIDC. + required: true + type: string + infisical-project-slug: + required: true + type: string + infisical-env-slug: + required: false + type: string + default: prod + infisical-secret-path: + required: false + type: string + default: / + oidc-audience: + required: false + type: string + default: "" + webhook-secret-name: + description: Shell-safe name of the secret that holds the Coolify webhook URL. + required: false + type: string + default: COOLIFY_WEBHOOK_URL + token-secret-name: + description: >- + Shell-safe name of the Coolify API token secret. Empty sends the + webhook with no bearer token. + required: false + type: string + default: COOLIFY_API_TOKEN + timeout-minutes: + required: false + type: number + default: 10 + outputs: + deployment-uuid: + description: Coolify deployment uuid from the webhook response. + value: ${{ jobs.deploy.outputs.deployment-uuid }} + +permissions: + id-token: write + contents: read + +jobs: + deploy: + runs-on: ${{ fromJSON(inputs.runner) }} + timeout-minutes: ${{ inputs.timeout-minutes }} + outputs: + deployment-uuid: ${{ steps.webhook.outputs.deployment-uuid }} + steps: + - uses: Infisical/secrets-action@v1.0.18 + with: + method: oidc + identity-id: ${{ inputs.infisical-identity-id }} + oidc-audience: ${{ inputs.oidc-audience }} + project-slug: ${{ inputs.infisical-project-slug }} + env-slug: ${{ inputs.infisical-env-slug }} + domain: ${{ inputs.infisical-domain }} + secret-path: ${{ inputs.infisical-secret-path }} + export-type: env + + - id: webhook + name: Post the Coolify deploy webhook + env: + WEBHOOK_SECRET_NAME: ${{ inputs.webhook-secret-name }} + TOKEN_SECRET_NAME: ${{ inputs.token-secret-name }} + run: | + set -euo pipefail + url="$(printenv "${WEBHOOK_SECRET_NAME}" || true)" + token="" + if [ -n "${TOKEN_SECRET_NAME}" ]; then + token="$(printenv "${TOKEN_SECRET_NAME}" || true)" + fi + if [ -z "${url}" ]; then + echo "::error::Infisical did not export ${WEBHOOK_SECRET_NAME}" + exit 1 + fi + body="${RUNNER_TEMP}/coolify-webhook.json" + if [ -n "${token}" ]; then + curl --fail-with-body -sS -X POST -H "Authorization: Bearer ${token}" -o "${body}" "${url}" + else + curl --fail-with-body -sS -X POST -o "${body}" "${url}" + fi + if ! uuid="$(node -e ' + const fs = require("node:fs"); + let parsed; + try { parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); } + catch { process.exit(2); } + const id = parsed.deployments?.[0]?.deployment_uuid ?? parsed.deployment_uuid ?? ""; + if (!id) process.exit(2); + process.stdout.write(String(id)); + ' "${body}")"; then + echo "::error::Coolify response missing deployment_uuid" + exit 1 + fi + echo "deployment-uuid=${uuid}" >> "$GITHUB_OUTPUT" + echo "deployment ${uuid}" diff --git a/.github/workflows/image.yml b/.github/workflows/image.yml new file mode 100644 index 0000000..fdabcd0 --- /dev/null +++ b/.github/workflows/image.yml @@ -0,0 +1,101 @@ +name: image + +on: + workflow_call: + inputs: + image: + description: GHCR image name, without a tag. + required: true + type: string + runner: + description: JSON array of runs-on labels. + required: false + type: string + default: '["ubuntu-latest"]' + context: + required: false + type: string + default: "." + file: + description: Dockerfile path. + required: false + type: string + default: Dockerfile + platforms: + description: buildx platforms. Empty builds the runner's own architecture. + required: false + type: string + default: "" + push: + required: false + type: boolean + default: true + npmrc: + description: >- + Mount the job token as an npmrc build secret so a Dockerfile can + install private packages. Not a build-arg, so it stays out of image + history. The job token is not a repository secret. + required: false + type: boolean + default: false + cache: + description: inline, gha, or none. + required: false + type: string + default: inline + extra-tags: + description: Extra image tags, one per line, after latest and the commit sha. + required: false + type: string + default: "" + timeout-minutes: + required: false + type: number + default: 30 + +permissions: + contents: read + packages: write + +jobs: + image: + runs-on: ${{ fromJSON(inputs.runner) }} + timeout-minutes: ${{ inputs.timeout-minutes }} + steps: + - uses: actions/checkout@v4 + + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ github.token }} + + - uses: docker/setup-buildx-action@v3 + + - id: tags + env: + IMAGE: ${{ inputs.image }} + SHA: ${{ github.sha }} + EXTRA: ${{ inputs.extra-tags }} + run: | + set -euo pipefail + { + echo "tags<> "$GITHUB_OUTPUT" + + - uses: docker/build-push-action@v6 + with: + context: ${{ inputs.context }} + file: ${{ inputs.file }} + push: ${{ inputs.push }} + platforms: ${{ inputs.platforms }} + tags: ${{ steps.tags.outputs.tags }} + secrets: ${{ inputs.npmrc && format('npmrc=//npm.pkg.github.com/:_authToken={0}', github.token) || '' }} + cache-from: ${{ inputs.cache == 'inline' && format('type=registry,ref={0}:latest', inputs.image) || (inputs.cache == 'gha' && 'type=gha' || '') }} + cache-to: ${{ inputs.cache == 'inline' && 'type=inline' || (inputs.cache == 'gha' && 'type=gha,mode=max' || '') }} diff --git a/.github/workflows/pr-guard.yml b/.github/workflows/pr-guard.yml new file mode 100644 index 0000000..6591c6f --- /dev/null +++ b/.github/workflows/pr-guard.yml @@ -0,0 +1,54 @@ +name: pr-guard + +on: + workflow_call: + inputs: + require-verification: + description: Fail unless the body has a ## Verification heading. + required: false + type: boolean + default: true + require-refs: + description: Fail unless the body has a Refs line naming an uppercase KEY-123. + required: false + type: boolean + default: true + scan-secrets: + description: Fail if the pull request diff adds a high-confidence secret shape. + required: false + type: boolean + default: false + runner: + description: JSON array of runs-on labels. + required: false + type: string + default: '["ubuntu-latest"]' + +permissions: + contents: read + +jobs: + check: + runs-on: ${{ fromJSON(inputs.runner) }} + timeout-minutes: 2 + steps: + - uses: actions/checkout@v4 + if: inputs.scan-secrets + with: + fetch-depth: 0 + + - uses: actions/checkout@v4 + with: + repository: PracticalWorks/.github + ref: ${{ github.repository == 'PracticalWorks/.github' && github.sha || 'v1' }} + path: .pw-shared + + - name: PR body and guardrails + env: + PR_BODY: ${{ github.event.pull_request.body }} + REQUIRE_VERIFICATION: ${{ inputs.require-verification }} + REQUIRE_REFS: ${{ inputs.require-refs }} + SCAN_SECRETS: ${{ inputs.scan-secrets }} + BASE_SHA: ${{ github.event.pull_request.base.sha }} + HEAD_SHA: ${{ github.sha }} + run: node .pw-shared/scripts/pr-guard.mjs diff --git a/.github/workflows/setup.yml b/.github/workflows/setup.yml new file mode 100644 index 0000000..9f42245 --- /dev/null +++ b/.github/workflows/setup.yml @@ -0,0 +1,69 @@ +name: setup + +# Install job. A later job cannot see this workspace, so test and image call +# the setup action in their own job instead of depending on this one. +on: + workflow_call: + inputs: + runner: + description: JSON array of runs-on labels, for example ["ubuntu-latest"]. + required: false + type: string + default: '["ubuntu-latest"]' + pnpm-version: + required: false + type: string + default: "10.14.0" + node-version: + required: false + type: string + default: "22" + node-architecture: + required: false + type: string + default: "" + registry-url: + required: false + type: string + default: "" + github-packages: + required: false + type: boolean + default: false + install: + required: false + type: boolean + default: true + run: + description: Shell to run after install. Empty skips it. + required: false + type: string + default: "" + timeout-minutes: + required: false + type: number + default: 15 + +permissions: + contents: read + +jobs: + setup: + runs-on: ${{ fromJSON(inputs.runner) }} + timeout-minutes: ${{ inputs.timeout-minutes }} + permissions: + contents: read + packages: read + steps: + - uses: actions/checkout@v4 + - uses: PracticalWorks/.github/.github/actions/setup@v1 + with: + pnpm-version: ${{ inputs.pnpm-version }} + node-version: ${{ inputs.node-version }} + node-architecture: ${{ inputs.node-architecture }} + registry-url: ${{ inputs.registry-url }} + github-packages: ${{ inputs.github-packages && 'true' || 'false' }} + install: ${{ inputs.install && 'true' || 'false' }} + - if: inputs.run != '' + name: run + run: ${{ inputs.run }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..363ba58 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,78 @@ +name: test + +on: + workflow_call: + inputs: + runner: + description: JSON array of runs-on labels, for example ["ubuntu-latest"]. + required: false + type: string + default: '["ubuntu-latest"]' + pnpm-version: + required: false + type: string + default: "10.14.0" + node-version: + required: false + type: string + default: "22" + node-architecture: + required: false + type: string + default: "" + registry-url: + required: false + type: string + default: "" + github-packages: + required: false + type: boolean + default: false + lint: + description: Shell for lint. Empty skips it. + required: false + type: string + default: "pnpm lint" + test: + description: Shell for tests. Empty skips it. + required: false + type: string + default: "pnpm test" + run: + description: Extra shell after lint and test. Empty skips it. + required: false + type: string + default: "" + timeout-minutes: + required: false + type: number + default: 30 + +permissions: + contents: read + +jobs: + test: + runs-on: ${{ fromJSON(inputs.runner) }} + timeout-minutes: ${{ inputs.timeout-minutes }} + permissions: + contents: read + packages: read + steps: + - uses: actions/checkout@v4 + - uses: PracticalWorks/.github/.github/actions/setup@v1 + with: + pnpm-version: ${{ inputs.pnpm-version }} + node-version: ${{ inputs.node-version }} + node-architecture: ${{ inputs.node-architecture }} + registry-url: ${{ inputs.registry-url }} + github-packages: ${{ inputs.github-packages && 'true' || 'false' }} + - if: inputs.lint != '' + name: lint + run: ${{ inputs.lint }} + - if: inputs.test != '' + name: test + run: ${{ inputs.test }} + - if: inputs.run != '' + name: run + run: ${{ inputs.run }} diff --git a/README.md b/README.md new file mode 100644 index 0000000..c7d0cd5 --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# Shared workflows + +Reusable workflows for Practical Works repositories. A job that calls one runs in the caller, so its minutes and logs stay on the caller. Private source is not checked out into a run of this repository. + +Consumers pin a tag: + +```yaml +jobs: + test: + uses: PracticalWorks/.github/.github/workflows/test.yml@v1 +``` + +`v1` is the floating major tag. Moving that tag in this repository is the one change that reaches every consumer pinned to it. Publish a commit here, then move `v1` to that commit. Do not pin `@main`. + +## Workflows + +| File | Job | +| --- | --- | +| `setup.yml` | checkout, pnpm, Node, frozen install, then an optional `run` command | +| `test.yml` | the same setup, then lint, test, and an optional extra command | +| `image.yml` | build a GHCR image and push `:latest` and `:` | +| `coolify-deploy.yml` | read secrets from Infisical with GitHub OIDC, then POST a Coolify webhook | +| `pr-guard.yml` | require a `## Verification` heading and a `Refs:` line; optional secret-shape scan | + +`test.yml` and `image.yml` call `.github/actions/setup` themselves. `setup.yml` is the install-only job. A following job cannot see the install from `setup.yml`. + +On macOS the setup action selects arm64 Node, so an Apple Silicon runner does not install an x64 build under Rosetta. Pass `node-architecture` to override it. + +`runner` is a JSON array of labels, for example `'["ubuntu-latest"]'` or `'["self-hosted","mini"]'`. + +## Secrets + +`coolify-deploy.yml` authenticates to Infisical with OIDC (`method: oidc`). The caller passes `infisical-identity-id` and `infisical-project-slug`. Those are public. The identity has to exist in Infisical and trust this caller repository before the job can read secrets. Callers do not declare repository secrets for that job. + +`image.yml` logs into GHCR with the job token. `npmrc: true` mounts that same token as a build secret for private package installs. It is not written into image history. + +## Pull request body + +`pr-guard.yml` fails a pull request whose body lacks `## Verification`, or a line `Refs: KEY-123` with an uppercase key, unless the caller turns that check off. `scan-secrets: true` fails the job when an added diff line matches a high-confidence credential shape. The log names the pattern, not the line. diff --git a/scripts/pr-guard.mjs b/scripts/pr-guard.mjs new file mode 100644 index 0000000..3a922c6 --- /dev/null +++ b/scripts/pr-guard.mjs @@ -0,0 +1,84 @@ +import { execFileSync } from "node:child_process"; +import { pathToFileURL } from "node:url"; + +const REF = "[A-Z][A-Z0-9]{1,11}-\\d{1,6}"; +const REFS_LINE = new RegExp(`^[ \\t]*Refs?[ \\t]*:[ \\t]*${REF}`, "m"); +const VERIFICATION = /^##[ \t]+Verification\b/m; + +const SECRET_RULES = [ + { name: "aws-access-key", re: /\bAKIA[0-9A-Z]{16}\b/ }, + { name: "github-pat", re: /\bghp_[A-Za-z0-9]{20,}\b/ }, + { name: "github-fine-grained", re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ }, + { name: "private-key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ }, + { name: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ }, +]; + +export function missingBody(body, options) { + const text = String(body ?? ""); + const missing = []; + if (options.verification && !VERIFICATION.test(text)) { + missing.push("a ## Verification section"); + } + if (options.refs && !REFS_LINE.test(text)) { + missing.push("a Refs: KEY-123 line"); + } + return missing; +} + +export function secretFindings(diff) { + const found = new Set(); + for (const line of String(diff).split("\n")) { + if (!line.startsWith("+") || line.startsWith("+++")) continue; + for (const rule of SECRET_RULES) { + if (rule.re.test(line)) found.add(rule.name); + } + } + return [...found]; +} + +function flag(name, fallback) { + const raw = process.env[name]; + if (raw == null || raw === "") return fallback; + return raw === "true" || raw === "1"; +} + +function scanSecrets() { + const base = process.env.BASE_SHA ?? ""; + const head = process.env.HEAD_SHA ?? ""; + if (!base || !head) { + console.error("guardrails: secret scan needs BASE_SHA and HEAD_SHA"); + return false; + } + const diff = execFileSync("git", ["diff", "--unified=0", base, head], { + encoding: "utf8", + }); + const hits = secretFindings(diff); + if (hits.length > 0) { + console.error(`guardrails: secret-shaped text in the diff (${hits.join(", ")})`); + return false; + } + return true; +} + +function main() { + const missing = missingBody(process.env.PR_BODY ?? "", { + verification: flag("REQUIRE_VERIFICATION", true), + refs: flag("REQUIRE_REFS", true), + }); + if (missing.length > 0) { + console.error(`pr body: missing ${missing.join(" and ")}`); + process.exitCode = 1; + return; + } + if (flag("SCAN_SECRETS", false) && !scanSecrets()) { + process.exitCode = 1; + return; + } + console.log("pr body ok"); +} + +const isMain = + process.argv[1] !== undefined && + import.meta.url === pathToFileURL(process.argv[1]).href; + +if (isMain) main(); diff --git a/scripts/pr-guard.test.mjs b/scripts/pr-guard.test.mjs new file mode 100644 index 0000000..b118b56 --- /dev/null +++ b/scripts/pr-guard.test.mjs @@ -0,0 +1,45 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { missingBody, secretFindings } from "./pr-guard.mjs"; + +const okBody = "## Verification\n\nChecked the shape.\n\nRefs: ABCD-12\n"; + +test("accepts a verification heading and an uppercase refs line", () => { + assert.deepEqual(missingBody(okBody, { verification: true, refs: true }), []); +}); + +test("names each missing piece", () => { + assert.deepEqual(missingBody("no contract here", { verification: true, refs: true }), [ + "a ## Verification section", + "a Refs: KEY-123 line", + ]); +}); + +test("refuses a lower-case ref", () => { + const missing = missingBody("## Verification\n\nRefs: abcd-12\n", { + verification: true, + refs: true, + }); + assert.deepEqual(missing, ["a Refs: KEY-123 line"]); +}); + +test("skips a check the caller turned off", () => { + assert.deepEqual(missingBody("Refs: ABCD-1\n", { verification: false, refs: true }), []); +}); + +test("secret scan reports the pattern and ignores context lines", () => { + const diff = [ + "+++ b/config.js", + "+const key = \"AKIAIOSFODNN7EXAMPLE\"", + " ghp_aaaaaaaaaaaaaaaaaaaa", + ].join("\n"); + assert.deepEqual(secretFindings(diff), ["aws-access-key"]); +}); + +test("secret scan sees a private key banner on an added line", () => { + assert.deepEqual( + secretFindings("+-----BEGIN OPENSSH PRIVATE KEY-----\n"), + ["private-key"], + ); +}); From 228cab2ed6c5ff509992099f6a7c4a36f9bf5136 Mon Sep 17 00:00:00 2001 From: echobob Date: Fri, 13 Nov 2026 17:22:53 -0500 Subject: [PATCH 2/3] Say which token permissions a caller job must grant. A called workflow can only lower the caller's token permissions, and these repositories default to read-only, so an image.yml caller without packages: write fails before any step runs. The README now lists what each workflow needs from its caller, and no longer says image.yml calls the setup action. Co-Authored-By: Claude Opus 5.5 --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c7d0cd5..e118e64 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,19 @@ jobs: | `coolify-deploy.yml` | read secrets from Infisical with GitHub OIDC, then POST a Coolify webhook | | `pr-guard.yml` | require a `## Verification` heading and a `Refs:` line; optional secret-shape scan | -`test.yml` and `image.yml` call `.github/actions/setup` themselves. `setup.yml` is the install-only job. A following job cannot see the install from `setup.yml`. +`test.yml` and `setup.yml` call `.github/actions/setup` themselves; `image.yml` installs nothing outside the Dockerfile. A following job cannot see the install from `setup.yml`. + +## Caller permissions + +A called workflow can only lower the token permissions its caller grants, never raise them, and Practical Works repositories default to a read-only token. A caller job that needs more grants it: + +| Workflow | Caller job needs | +| --- | --- | +| `image.yml` | `permissions: { contents: read, packages: write }` | +| `coolify-deploy.yml` | `permissions: { contents: read, id-token: write }` | +| `setup.yml`, `test.yml`, `pr-guard.yml` | nothing beyond the read-only default | + +Without it the workflow run fails before any step starts, because the nested job asks for a permission the caller never granted. On macOS the setup action selects arm64 Node, so an Apple Silicon runner does not install an x64 build under Rosetta. Pass `node-architecture` to override it. From b642a37752e30e5a98ac2ff2d5912216e165d6be Mon Sep 17 00:00:00 2001 From: jcotillo Date: Mon, 16 Nov 2026 22:19:52 -0500 Subject: [PATCH 3/3] Release v1.1.0: node on self-hosted runners, annotated failures, proven deploys. pr-guard.yml sets up Node 22 before its script, because the Proxmox runners ship without node (FACT-1952), and checks the script out at job.workflow_sha, the commit of the workflow file the caller invoked, instead of hard-coding v1. Every pr-guard failure is also emitted as an ::error:: command (% CR LF escaped), so the reason survives as a check annotation when a runner loses the job log (FACT-1971). coolify-deploy.yml now waits for Coolify's real outcome: it polls /api/v1/deployments/ on the webhook's origin until finished, fails on failed or cancelled, and, given health-url and expected-version, polls that URL until it serves the version (FACT-1910). The webhook URL and token are masked. Refs: FACT-1885 Refs: FACT-1910 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 7 +- .github/workflows/coolify-deploy.yml | 77 +++++----- .github/workflows/pr-guard.yml | 18 ++- README.md | 46 +++++- scripts/coolify-deploy.mjs | 203 +++++++++++++++++++++++++++ scripts/coolify-deploy.test.mjs | 175 +++++++++++++++++++++++ scripts/pr-guard.mjs | 31 +++- scripts/pr-guard.test.mjs | 44 +++++- 8 files changed, 558 insertions(+), 43 deletions(-) create mode 100644 scripts/coolify-deploy.mjs create mode 100644 scripts/coolify-deploy.test.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b0212d4..a941f6d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,8 +13,11 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: pr-guard unit tests - run: node --test scripts/pr-guard.test.mjs + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: script unit tests + run: node --test scripts/*.test.mjs guard: if: github.event_name == 'pull_request' diff --git a/.github/workflows/coolify-deploy.yml b/.github/workflows/coolify-deploy.yml index b671255..d965a11 100644 --- a/.github/workflows/coolify-deploy.yml +++ b/.github/workflows/coolify-deploy.yml @@ -3,6 +3,9 @@ name: coolify-deploy # The job runs in the caller, on the caller's minutes. Secrets are read from # Infisical with this workflow's GitHub OIDC token. Callers pass the identity # id and project slug; they do not pass repository secrets. +# +# The job goes green only once Coolify reports the deployment finished, and, +# when health-url is set, once that URL serves expected-version (FACT-1910). on: workflow_call: inputs: @@ -41,15 +44,30 @@ on: default: COOLIFY_WEBHOOK_URL token-secret-name: description: >- - Shell-safe name of the Coolify API token secret. Empty sends the - webhook with no bearer token. + Shell-safe name of the Coolify API token secret. It authorizes the + webhook and the deployment status polls, so it is required. required: false type: string default: COOLIFY_API_TOKEN timeout-minutes: + description: >- + Job timeout. The deploy, the wait for Coolify's outcome, and the + health-url wait share it, less one minute so the job fails by name. required: false type: number default: 10 + health-url: + description: >- + Optional URL polled after Coolify reports finished, until its body + contains expected-version. Pass both or neither. + required: false + type: string + default: "" + expected-version: + description: Optional text (e.g. the git sha) health-url must serve. + required: false + type: string + default: "" outputs: deployment-uuid: description: Coolify deployment uuid from the webhook response. @@ -77,39 +95,34 @@ jobs: secret-path: ${{ inputs.infisical-secret-path }} export-type: env + # The deploy script comes from the same commit as this workflow file. + # The fallback is only for a runner that leaves job.workflow_sha empty; + # bump it with each release tag. + - uses: actions/checkout@v4 + with: + repository: ${{ job.workflow_repository || 'PracticalWorks/.github' }} + ref: ${{ job.workflow_sha || 'v1.1.0' }} + path: .pw-shared + + # Self-hosted runners (Proxmox ephemeral) ship without node. + - uses: actions/setup-node@v4 + with: + node-version: 22 + - id: webhook - name: Post the Coolify deploy webhook + name: Deploy on Coolify and prove it is live env: WEBHOOK_SECRET_NAME: ${{ inputs.webhook-secret-name }} TOKEN_SECRET_NAME: ${{ inputs.token-secret-name }} + HEALTH_URL: ${{ inputs.health-url }} + EXPECTED_VERSION: ${{ inputs.expected-version }} + TIMEOUT_MINUTES: ${{ inputs.timeout-minutes }} run: | set -euo pipefail - url="$(printenv "${WEBHOOK_SECRET_NAME}" || true)" - token="" - if [ -n "${TOKEN_SECRET_NAME}" ]; then - token="$(printenv "${TOKEN_SECRET_NAME}" || true)" - fi - if [ -z "${url}" ]; then - echo "::error::Infisical did not export ${WEBHOOK_SECRET_NAME}" - exit 1 - fi - body="${RUNNER_TEMP}/coolify-webhook.json" - if [ -n "${token}" ]; then - curl --fail-with-body -sS -X POST -H "Authorization: Bearer ${token}" -o "${body}" "${url}" - else - curl --fail-with-body -sS -X POST -o "${body}" "${url}" - fi - if ! uuid="$(node -e ' - const fs = require("node:fs"); - let parsed; - try { parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); } - catch { process.exit(2); } - const id = parsed.deployments?.[0]?.deployment_uuid ?? parsed.deployment_uuid ?? ""; - if (!id) process.exit(2); - process.stdout.write(String(id)); - ' "${body}")"; then - echo "::error::Coolify response missing deployment_uuid" - exit 1 - fi - echo "deployment-uuid=${uuid}" >> "$GITHUB_OUTPUT" - echo "deployment ${uuid}" + # Mask both values before anything can print them. printenv does + # not echo; the ::add-mask:: line itself is not shown in the log. + for name in "${WEBHOOK_SECRET_NAME:-COOLIFY_WEBHOOK_URL}" "${TOKEN_SECRET_NAME:-COOLIFY_API_TOKEN}"; do + value="$(printenv "${name}" || true)" + if [ -n "${value}" ]; then echo "::add-mask::${value}"; fi + done + node .pw-shared/scripts/coolify-deploy.mjs diff --git a/.github/workflows/pr-guard.yml b/.github/workflows/pr-guard.yml index 6591c6f..ebe675a 100644 --- a/.github/workflows/pr-guard.yml +++ b/.github/workflows/pr-guard.yml @@ -37,12 +37,26 @@ jobs: with: fetch-depth: 0 + # The script comes from the same commit as this workflow file, so a caller + # pinned to a tag runs that tag's script. job.workflow_sha names the commit + # of the file that defines this job (the reusable workflow, not the caller). + # The fallback is only for a runner that leaves it empty; bump it with + # each release tag. - uses: actions/checkout@v4 with: - repository: PracticalWorks/.github - ref: ${{ github.repository == 'PracticalWorks/.github' && github.sha || 'v1' }} + repository: ${{ job.workflow_repository || 'PracticalWorks/.github' }} + ref: ${{ job.workflow_sha || 'v1.1.0' }} path: .pw-shared + - name: Warn when the runner gave no workflow sha + if: job.workflow_sha == '' + run: echo "::warning::job.workflow_sha is empty on this runner, so pr-guard ran the v1.1.0 script" + + # Self-hosted runners (Proxmox ephemeral) ship without node. + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: PR body and guardrails env: PR_BODY: ${{ github.event.pull_request.body }} diff --git a/README.md b/README.md index e118e64..9ed87ef 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,19 @@ Consumers pin a tag: ```yaml jobs: test: - uses: PracticalWorks/.github/.github/workflows/test.yml@v1 + uses: PracticalWorks/.github/.github/workflows/test.yml@v1.1.0 ``` -`v1` is the floating major tag. Moving that tag in this repository is the one change that reaches every consumer pinned to it. Publish a commit here, then move `v1` to that commit. Do not pin `@main`. +## Tags + +| Tag | Commit | What it adds | +| --- | --- | --- | +| `v1` | the first release | the five workflows and the setup action | +| `v1.1.0` | the merge of the v1.1.0 pull request | `pr-guard.yml` sets up Node and runs its own commit's script; failures are also `::error::` annotations; `coolify-deploy.yml` waits for Coolify's real outcome and can prove a version is live | + +A release is a new tag on a commit of `main`. Existing tags are never moved or deleted, so a caller sees a change only when it bumps its pin. Do not pin `@main`. + +`pr-guard.yml` and `coolify-deploy.yml` check out this repository's scripts at `job.workflow_sha`, the commit of the workflow file the caller invoked, so a caller pinned to `v1.1.0` runs `v1.1.0`'s scripts. If a runner leaves `job.workflow_sha` empty, they fall back to a tag written into the workflow file and say so with a warning. A release bumps that fallback to its own tag. ## Workflows @@ -19,7 +28,7 @@ jobs: | `setup.yml` | checkout, pnpm, Node, frozen install, then an optional `run` command | | `test.yml` | the same setup, then lint, test, and an optional extra command | | `image.yml` | build a GHCR image and push `:latest` and `:` | -| `coolify-deploy.yml` | read secrets from Infisical with GitHub OIDC, then POST a Coolify webhook | +| `coolify-deploy.yml` | read secrets from Infisical with GitHub OIDC, POST a Coolify webhook, then wait until the deploy is proven live | | `pr-guard.yml` | require a `## Verification` heading and a `Refs:` line; optional secret-shape scan | `test.yml` and `setup.yml` call `.github/actions/setup` themselves; `image.yml` installs nothing outside the Dockerfile. A following job cannot see the install from `setup.yml`. @@ -46,6 +55,37 @@ On macOS the setup action selects arm64 Node, so an Apple Silicon runner does no `image.yml` logs into GHCR with the job token. `npmrc: true` mounts that same token as a build secret for private package installs. It is not written into image history. +## Coolify deploy + +The job goes green only when the deploy is live, not when Coolify accepts the webhook: + +1. It posts the webhook with the bearer token and reads the deployment uuid from the answer (the `deployment-uuid` output). +2. It polls `GET /api/v1/deployments/` on the webhook URL's origin with the same token every 10 seconds, until Coolify reports `finished`. `failed`, `cancelled` or `cancelled-by-user` fails the job. A 4xx fails at once; an unreachable Coolify (a network drop, a 5xx) is retried six times in a row. +3. If the caller passes `health-url` and `expected-version`, it polls `health-url` every 5 seconds until the body contains `expected-version`, for example the git sha the image was built from. + +| Input | Default | Meaning | +| --- | --- | --- | +| `health-url` | empty | URL to poll after Coolify reports `finished`. Pass it with `expected-version`, or leave both empty | +| `expected-version` | empty | text `health-url` must serve, e.g. `${{ github.sha }}` | +| `timeout-minutes` | `10` | job timeout. All three phases share it, less one minute, so a slow deploy fails with an `::error::` naming the phase instead of being killed | +| `token-secret-name` | `COOLIFY_API_TOKEN` | the token now also authorizes the status polls, so it is required. It needs deploy and read scope | + +```yaml +jobs: + deploy: + permissions: { contents: read, id-token: write } + uses: PracticalWorks/.github/.github/workflows/coolify-deploy.yml@v1.1.0 + with: + infisical-identity-id: + infisical-project-slug: + health-url: https://app.example.com/health + expected-version: ${{ github.sha }} +``` + +The webhook URL and the token are masked with `::add-mask::` before anything runs, and error messages name only the request path and status, never a response body. + ## Pull request body `pr-guard.yml` fails a pull request whose body lacks `## Verification`, or a line `Refs: KEY-123` with an uppercase key, unless the caller turns that check off. `scan-secrets: true` fails the job when an added diff line matches a high-confidence credential shape. The log names the pattern, not the line. + +Every failure is printed to the log and also emitted as an `::error::` workflow command, so the reason shows as an annotation on the check even when a self-hosted runner loses the job log. The workflow sets up Node 22 itself, so it runs on self-hosted runners that ship without Node. diff --git a/scripts/coolify-deploy.mjs b/scripts/coolify-deploy.mjs new file mode 100644 index 0000000..401c789 --- /dev/null +++ b/scripts/coolify-deploy.mjs @@ -0,0 +1,203 @@ +/** + * Posts the Coolify deploy webhook, then proves the deploy instead of trusting + * the trigger (FACT-1910). + * + * The webhook only says Coolify queued a deployment. A deploy that then fails + * (a bad image, a healthcheck that never passes, so the rolling update keeps + * the old container) would leave the job green while the old code serves. So + * this polls GET /api/v1/deployments/ on the webhook's own origin until + * Coolify reports `finished`, and fails on `failed` or `cancelled`. When the + * caller names a health URL and an expected version, it then polls that URL + * until the body contains the version. Modeled on PracticalWorks/frontdesk + * scripts/ci/deploy-coolify.mjs (HOMEINFRA-498). + * + * The webhook URL and token are secrets: neither is ever printed, and error + * bodies are never echoed because they can carry env values. + */ +import { appendFileSync } from "node:fs"; +import { pathToFileURL } from "node:url"; + +import { reportFailure } from "./pr-guard.mjs"; + +const DONE_OK = "finished"; +const DONE_BAD = ["failed", "cancelled", "cancelled-by-user"]; +/** Polls in a row that may fail to reach Coolify before the job gives up. */ +const MAX_POLL_MISSES = 6; + +const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); + +export class HttpError extends Error { + constructor(method, url, status, bytes) { + // Only the path is named: the webhook query string identifies the app. + super(`${method} ${new URL(url).pathname} -> HTTP ${status} (body redacted, ${bytes} bytes)`); + this.status = status; + } +} + +/** The Coolify API base is the webhook URL's origin. */ +export function coolifyBase(webhookUrl) { + return new URL(webhookUrl).origin; +} + +export function deploymentUuid(parsed) { + return String(parsed?.deployments?.[0]?.deployment_uuid ?? parsed?.deployment_uuid ?? ""); +} + +async function request(fetchImpl, method, url, token) { + const headers = token ? { Authorization: `Bearer ${token}` } : {}; + const res = await fetchImpl(url, { method, headers }); + const text = await res.text(); + if (!res.ok) throw new HttpError(method, url, res.status, text.length); + return text; +} + +export async function triggerDeploy({ webhookUrl, token, fetchImpl = fetch }) { + const text = await request(fetchImpl, "POST", webhookUrl, token); + let parsed; + try { + parsed = JSON.parse(text); + } catch { + throw new Error("Coolify webhook answered with a body that is not JSON"); + } + const id = deploymentUuid(parsed); + if (!id) throw new Error("Coolify response missing deployment_uuid"); + return id; +} + +/** + * Polls the deployment until Coolify reports an end state. A 4xx is a real + * answer (a bad token, an unknown deployment) and fails at once; an + * unreachable Coolify (a network drop, a 5xx) is retried up to + * MAX_POLL_MISSES times in a row. + */ +export async function waitForDeployment({ + base, + token, + uuid, + deadline, + fetchImpl = fetch, + sleep = defaultSleep, + now = Date.now, + pollMs = 10_000, + log = console.log, +}) { + const url = `${base}/api/v1/deployments/${encodeURIComponent(uuid)}`; + let last = ""; + let misses = 0; + for (;;) { + let status; + try { + status = String(JSON.parse(await request(fetchImpl, "GET", url, token)).status ?? ""); + misses = 0; + } catch (err) { + if ((err.status && err.status < 500) || ++misses > MAX_POLL_MISSES) throw err; + log(`deployment ${uuid}: poll failed (${err.message}), retrying (${misses}/${MAX_POLL_MISSES})`); + status = last; + } + if (status !== last) log(`deployment ${uuid}: ${status}`); + last = status; + if (status === DONE_OK) return; + if (DONE_BAD.includes(status)) { + throw new Error( + `Coolify deployment ${uuid} ended ${status}: the previous version is still serving (see its Deployment Logs)`, + ); + } + if (now() + pollMs > deadline) { + throw new Error(`Coolify deployment ${uuid} still ${last || "unknown"} at the timeout`); + } + await sleep(pollMs); + } +} + +/** Polls the health URL until its body contains the expected version. */ +export async function waitForVersion({ + healthUrl, + expectedVersion, + deadline, + fetchImpl = fetch, + sleep = defaultSleep, + now = Date.now, + pollMs = 5_000, + log = console.log, +}) { + let last = "no answer yet"; + for (;;) { + try { + const body = await request(fetchImpl, "GET", healthUrl, ""); + if (body.includes(expectedVersion)) { + log(`${new URL(healthUrl).pathname} serves ${expectedVersion}`); + return; + } + last = `answered without ${expectedVersion} (${body.length} bytes)`; + } catch (err) { + last = err instanceof HttpError ? err.message : `unreachable (${err.message})`; + } + if (now() + pollMs > deadline) { + throw new Error(`${new URL(healthUrl).pathname} never served ${expectedVersion}: last ${last}`); + } + await sleep(pollMs); + } +} + +export async function deployAndProve({ + webhookUrl, + token, + healthUrl = "", + expectedVersion = "", + timeoutMs, + setOutput = () => {}, + ...io +}) { + if (!webhookUrl) throw new Error("no Coolify webhook URL"); + if (!token) throw new Error("no Coolify API token: the deploy cannot be proven without one"); + if (Boolean(healthUrl) !== Boolean(expectedVersion)) { + throw new Error("health-url and expected-version go together: pass both or neither"); + } + const now = io.now ?? Date.now; + const deadline = now() + timeoutMs; + const uuid = await triggerDeploy({ webhookUrl, token, fetchImpl: io.fetchImpl }); + setOutput(uuid); + (io.log ?? console.log)(`Coolify deployment ${uuid} queued`); + await waitForDeployment({ ...io, base: coolifyBase(webhookUrl), token, uuid, deadline }); + if (healthUrl) await waitForVersion({ ...io, healthUrl, expectedVersion, deadline }); + return uuid; +} + +/** Leaves a minute of the job's timeout-minutes so the job fails here, by name. */ +export function budgetMs(timeoutMinutes) { + const minutes = Number(timeoutMinutes) || 10; + return Math.max(60_000, (minutes - 1) * 60_000); +} + +async function main() { + const env = process.env; + const webhookName = env.WEBHOOK_SECRET_NAME || "COOLIFY_WEBHOOK_URL"; + const tokenName = env.TOKEN_SECRET_NAME || "COOLIFY_API_TOKEN"; + const webhookUrl = env[webhookName] ?? ""; + const token = env[tokenName] ?? ""; + try { + if (!webhookUrl) throw new Error(`Infisical did not export ${webhookName}`); + if (!token) { + throw new Error(`Infisical did not export ${tokenName}: the deploy cannot be proven without it`); + } + await deployAndProve({ + webhookUrl, + token, + healthUrl: env.HEALTH_URL ?? "", + expectedVersion: env.EXPECTED_VERSION ?? "", + timeoutMs: budgetMs(env.TIMEOUT_MINUTES), + setOutput: (uuid) => { + if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `deployment-uuid=${uuid}\n`); + }, + }); + } catch (err) { + reportFailure(err.message); + process.exitCode = 1; + } +} + +const isMain = + process.argv[1] !== undefined && + import.meta.url === pathToFileURL(process.argv[1]).href; + +if (isMain) await main(); diff --git a/scripts/coolify-deploy.test.mjs b/scripts/coolify-deploy.test.mjs new file mode 100644 index 0000000..60877a8 --- /dev/null +++ b/scripts/coolify-deploy.test.mjs @@ -0,0 +1,175 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { + budgetMs, + coolifyBase, + deployAndProve, + waitForDeployment, + waitForVersion, +} from "./coolify-deploy.mjs"; + +const WEBHOOK = "https://cd.example.test/api/v1/deploy?uuid=app123&force=false"; +const TOKEN = "test-token"; + +/** A fake clock that advances only when the code under test sleeps. */ +function clock() { + let t = 0; + return { now: () => t, sleep: async (ms) => { t += ms; } }; +} + +function respond(status, body) { + const text = typeof body === "string" ? body : JSON.stringify(body); + return { ok: status >= 200 && status < 300, status, text: async () => text }; +} + +/** Routes each call to the next scripted answer for its method and path. */ +function fakeFetch(script) { + const calls = []; + const fetchImpl = async (url, init) => { + const u = new URL(url); + const key = `${init.method} ${u.origin}${u.pathname}`; + calls.push({ key, auth: init.headers.Authorization }); + const queue = script[key]; + if (!queue || queue.length === 0) throw new Error(`unscripted call ${key}`); + const next = queue.length > 1 ? queue.shift() : queue[0]; + if (next instanceof Error) throw next; + return next; + }; + return { fetchImpl, calls }; +} + +const POST = "POST https://cd.example.test/api/v1/deploy"; +const STATUS = "GET https://cd.example.test/api/v1/deployments/dep-1"; +const HEALTH = "GET https://app.example.test/health"; + +test("the Coolify base is the webhook's origin", () => { + assert.equal(coolifyBase(WEBHOOK), "https://cd.example.test"); +}); + +test("waits through queued and in_progress to finished, with the bearer token", async () => { + const { fetchImpl, calls } = fakeFetch({ + [POST]: [respond(200, { deployments: [{ deployment_uuid: "dep-1" }] })], + [STATUS]: [ + respond(200, { status: "queued" }), + respond(200, { status: "in_progress" }), + respond(200, { status: "finished" }), + ], + }); + const outputs = []; + const uuid = await deployAndProve({ + webhookUrl: WEBHOOK, + token: TOKEN, + timeoutMs: 600_000, + setOutput: (id) => outputs.push(id), + fetchImpl, + ...clock(), + log: () => {}, + }); + assert.equal(uuid, "dep-1"); + assert.deepEqual(outputs, ["dep-1"]); + assert.equal(calls.filter((c) => c.key === STATUS).length, 3); + assert.ok(calls.every((c) => c.auth === `Bearer ${TOKEN}`)); +}); + +for (const end of ["failed", "cancelled", "cancelled-by-user"]) { + test(`a deployment that ends ${end} fails by name`, async () => { + const { fetchImpl } = fakeFetch({ [STATUS]: [respond(200, { status: end })] }); + await assert.rejects( + waitForDeployment({ + base: "https://cd.example.test", + token: TOKEN, + uuid: "dep-1", + deadline: 600_000, + fetchImpl, + ...clock(), + log: () => {}, + }), + new RegExp(`dep-1 ended ${end}`), + ); + }); +} + +test("a 5xx poll is retried; a 4xx poll fails at once", async () => { + const flaky = fakeFetch({ + [STATUS]: [respond(502, "bad gateway"), new TypeError("fetch failed"), respond(200, { status: "finished" })], + }); + await waitForDeployment({ + base: "https://cd.example.test", token: TOKEN, uuid: "dep-1", deadline: 600_000, + fetchImpl: flaky.fetchImpl, ...clock(), log: () => {}, + }); + const denied = fakeFetch({ [STATUS]: [respond(401, "SECRET-ish body")] }); + await assert.rejects( + waitForDeployment({ + base: "https://cd.example.test", token: TOKEN, uuid: "dep-1", deadline: 600_000, + fetchImpl: denied.fetchImpl, ...clock(), log: () => {}, + }), + (err) => /HTTP 401 \(body redacted, 15 bytes\)/.test(err.message) && !err.message.includes("SECRET"), + ); +}); + +test("a deployment still running at the deadline fails", async () => { + const { fetchImpl } = fakeFetch({ [STATUS]: [respond(200, { status: "in_progress" })] }); + await assert.rejects( + waitForDeployment({ + base: "https://cd.example.test", token: TOKEN, uuid: "dep-1", deadline: 60_000, + fetchImpl, ...clock(), log: () => {}, + }), + /dep-1 still in_progress at the timeout/, + ); +}); + +test("then waits for the health URL to serve the expected version", async () => { + const { fetchImpl, calls } = fakeFetch({ + [POST]: [respond(200, { deployment_uuid: "dep-1" })], + [STATUS]: [respond(200, { status: "finished" })], + [HEALTH]: [respond(503, "booting"), respond(200, '{"version":"old"}'), respond(200, '{"version":"abc123"}')], + }); + await deployAndProve({ + webhookUrl: WEBHOOK, token: TOKEN, healthUrl: "https://app.example.test/health", + expectedVersion: "abc123", timeoutMs: 600_000, fetchImpl, ...clock(), log: () => {}, + }); + assert.equal(calls.filter((c) => c.key === HEALTH).length, 3); + assert.ok(calls.filter((c) => c.key === HEALTH).every((c) => c.auth === undefined)); +}); + +test("a health URL that never serves the version fails, naming the last answer", async () => { + const { fetchImpl } = fakeFetch({ [HEALTH]: [respond(200, '{"version":"old"}')] }); + await assert.rejects( + waitForVersion({ + healthUrl: "https://app.example.test/health", expectedVersion: "abc123", deadline: 30_000, + fetchImpl, ...clock(), log: () => {}, + }), + /\/health never served abc123: last answered without abc123/, + ); +}); + +test("refuses to run without a token, or with only one of health-url and expected-version", async () => { + await assert.rejects(deployAndProve({ webhookUrl: WEBHOOK, token: "", timeoutMs: 1 }), /no Coolify API token/); + await assert.rejects( + deployAndProve({ webhookUrl: WEBHOOK, token: TOKEN, healthUrl: "https://app.example.test/health", timeoutMs: 1 }), + /go together/, + ); +}); + +test("a webhook answer without a deployment uuid fails", async () => { + const { fetchImpl } = fakeFetch({ [POST]: [respond(200, { message: "ok" })] }); + await assert.rejects( + deployAndProve({ webhookUrl: WEBHOOK, token: TOKEN, timeoutMs: 600_000, fetchImpl, ...clock(), log: () => {} }), + /missing deployment_uuid/, + ); +}); + +test("a webhook error never echoes the query string or the body", async () => { + const { fetchImpl } = fakeFetch({ [POST]: [respond(403, "token=abc")] }); + await assert.rejects( + deployAndProve({ webhookUrl: WEBHOOK, token: TOKEN, timeoutMs: 600_000, fetchImpl, ...clock(), log: () => {} }), + (err) => err.message === "POST /api/v1/deploy -> HTTP 403 (body redacted, 9 bytes)", + ); +}); + +test("the poll budget leaves a minute of the job timeout", () => { + assert.equal(budgetMs(10), 9 * 60_000); + assert.equal(budgetMs(1), 60_000); + assert.equal(budgetMs(""), 9 * 60_000); +}); diff --git a/scripts/pr-guard.mjs b/scripts/pr-guard.mjs index 3a922c6..ae4fde6 100644 --- a/scripts/pr-guard.mjs +++ b/scripts/pr-guard.mjs @@ -13,6 +13,31 @@ const SECRET_RULES = [ { name: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ }, ]; +/** + * Escapes a message for a GitHub workflow command, as GitHub's toolkit does: + * % first, then CR and LF, so a multi-line message stays one annotation. + */ +export function escapeCommandData(message) { + return String(message) + .replace(/%/g, "%25") + .replace(/\r/g, "%0D") + .replace(/\n/g, "%0A"); +} + +export function errorCommand(message) { + return `::error::${escapeCommandData(message)}`; +} + +/** + * Prints a failure to stderr for the job log, and again as an `::error::` + * command so it also lands as a check annotation. The annotation survives + * when a self-hosted runner loses the job log (FACT-1971). + */ +export function reportFailure(message, write = { err: console.error, out: console.log }) { + write.err(message); + write.out(errorCommand(message)); +} + export function missingBody(body, options) { const text = String(body ?? ""); const missing = []; @@ -46,7 +71,7 @@ function scanSecrets() { const base = process.env.BASE_SHA ?? ""; const head = process.env.HEAD_SHA ?? ""; if (!base || !head) { - console.error("guardrails: secret scan needs BASE_SHA and HEAD_SHA"); + reportFailure("guardrails: secret scan needs BASE_SHA and HEAD_SHA"); return false; } const diff = execFileSync("git", ["diff", "--unified=0", base, head], { @@ -54,7 +79,7 @@ function scanSecrets() { }); const hits = secretFindings(diff); if (hits.length > 0) { - console.error(`guardrails: secret-shaped text in the diff (${hits.join(", ")})`); + reportFailure(`guardrails: secret-shaped text in the diff (${hits.join(", ")})`); return false; } return true; @@ -66,7 +91,7 @@ function main() { refs: flag("REQUIRE_REFS", true), }); if (missing.length > 0) { - console.error(`pr body: missing ${missing.join(" and ")}`); + reportFailure(`pr body: missing ${missing.join(" and ")}`); process.exitCode = 1; return; } diff --git a/scripts/pr-guard.test.mjs b/scripts/pr-guard.test.mjs index b118b56..08970be 100644 --- a/scripts/pr-guard.test.mjs +++ b/scripts/pr-guard.test.mjs @@ -1,7 +1,14 @@ import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; import { test } from "node:test"; +import { fileURLToPath } from "node:url"; -import { missingBody, secretFindings } from "./pr-guard.mjs"; +import { + escapeCommandData, + missingBody, + reportFailure, + secretFindings, +} from "./pr-guard.mjs"; const okBody = "## Verification\n\nChecked the shape.\n\nRefs: ABCD-12\n"; @@ -43,3 +50,38 @@ test("secret scan sees a private key banner on an added line", () => { ["private-key"], ); }); + +test("escapes %, CR and LF so a message is one workflow command", () => { + assert.equal(escapeCommandData("100% done\r\nnext\nline"), "100%25 done%0D%0Anext%0Aline"); + assert.equal(escapeCommandData("%0A"), "%250A"); +}); + +test("a failure goes to stderr and out again as an ::error:: annotation", () => { + const err = []; + const out = []; + reportFailure("pr body: missing a Refs: KEY-123 line\nsecond", { + err: (m) => err.push(m), + out: (m) => out.push(m), + }); + assert.deepEqual(err, ["pr body: missing a Refs: KEY-123 line\nsecond"]); + assert.deepEqual(out, ["::error::pr body: missing a Refs: KEY-123 line%0Asecond"]); +}); + +test("the CLI prints the missing body pieces as an ::error:: command", () => { + const run = spawnSync(process.execPath, [fileURLToPath(new URL("./pr-guard.mjs", import.meta.url))], { + env: { ...process.env, PR_BODY: "no contract", REQUIRE_VERIFICATION: "true", REQUIRE_REFS: "true", SCAN_SECRETS: "false" }, + encoding: "utf8", + }); + assert.equal(run.status, 1); + assert.match(run.stderr, /^pr body: missing a ## Verification section and a Refs: KEY-123 line$/m); + assert.match(run.stdout, /^::error::pr body: missing a ## Verification section and a Refs: KEY-123 line$/m); +}); + +test("the CLI emits no ::error:: for a good body", () => { + const run = spawnSync(process.execPath, [fileURLToPath(new URL("./pr-guard.mjs", import.meta.url))], { + env: { ...process.env, PR_BODY: okBody, SCAN_SECRETS: "false" }, + encoding: "utf8", + }); + assert.equal(run.status, 0); + assert.doesNotMatch(run.stdout, /::error::/); +});