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..e118e64 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# 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 `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. + +## 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"], + ); +});