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..a941f6d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,27 @@ +name: ci + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + guard-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - 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' + 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..d965a11 --- /dev/null +++ b/.github/workflows/coolify-deploy.yml @@ -0,0 +1,128 @@ +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: + 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. 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. + 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 + + # 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: 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 + # 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/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..ebe675a --- /dev/null +++ b/.github/workflows/pr-guard.yml @@ -0,0 +1,68 @@ +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 + + # 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: ${{ 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 }} + 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..9ed87ef --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# 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.1.0 +``` + +## 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 + +| 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, 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`. + +## 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. + +`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. + +## 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 new file mode 100644 index 0000000..ae4fde6 --- /dev/null +++ b/scripts/pr-guard.mjs @@ -0,0 +1,109 @@ +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,}/ }, +]; + +/** + * 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 = []; + 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) { + reportFailure("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) { + reportFailure(`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) { + reportFailure(`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..08970be --- /dev/null +++ b/scripts/pr-guard.test.mjs @@ -0,0 +1,87 @@ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { test } from "node:test"; +import { fileURLToPath } from "node:url"; + +import { + escapeCommandData, + missingBody, + reportFailure, + 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"], + ); +}); + +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::/); +});