From 09a107bcb8c24e340f0e0fa38ba51d1cf85af2a4 Mon Sep 17 00:00:00 2001 From: echobob Date: Thu, 12 Nov 2026 23:48:26 -0500 Subject: [PATCH 1/2] 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/2] 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.