From e82363220d431dadf866d8a6d2d32b9b6db3fc35 Mon Sep 17 00:00:00 2001 From: jcotillo Date: Tue, 17 Nov 2026 09:45:18 -0500 Subject: [PATCH] =?UTF-8?q?ci(workflows):=20v1.2.0=20=E2=80=94=20coolify-d?= =?UTF-8?q?eploy=20runs=20in=20the=20caller's=20environment;=20setup=20can?= =?UTF-8?q?=20skip=20the=20pnpm=20cache=20[FACT-1910]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An Infisical OIDC identity that trusts `...:environment:` only matches a token requested by a job running in that environment, and a caller job that `uses:` this workflow cannot set `environment:`. coolify-deploy.yml takes `environment` (empty = none) and `deployment` (default true; false for a caller that writes its own Deployment records) and runs its deploy job there. The setup action takes `cache` (default true) so a caller whose runners keep the pnpm store can skip the save and restore. The Infisical action is pinned by commit; the script fallback refs move to v1.2.0. A test pins all three. Refs: FACT-1910 Co-Authored-By: Claude Opus 5.5 --- .github/actions/setup/action.yml | 9 ++++- .github/workflows/coolify-deploy.yml | 31 +++++++++++++++-- .github/workflows/pr-guard.yml | 4 +-- README.md | 21 ++++++++++-- scripts/workflows.test.mjs | 51 ++++++++++++++++++++++++++++ 5 files changed, 108 insertions(+), 8 deletions(-) create mode 100644 scripts/workflows.test.mjs diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml index 6c37a23..1acc810 100644 --- a/.github/actions/setup/action.yml +++ b/.github/actions/setup/action.yml @@ -28,6 +28,13 @@ inputs: job needs packages:read. required: false default: "false" + cache: + description: >- + When true, actions/setup-node caches the pnpm store. A caller whose + runners keep the store between jobs turns it off to skip the cache + save and restore. + required: false + default: "true" install: description: Run pnpm install --frozen-lockfile after setup. required: false @@ -44,7 +51,7 @@ runs: with: node-version: ${{ inputs.node-version }} architecture: ${{ inputs.node-architecture != '' && inputs.node-architecture || (runner.os == 'macOS' && 'arm64' || '') }} - cache: pnpm + cache: ${{ inputs.cache == 'true' && 'pnpm' || '' }} registry-url: ${{ inputs.registry-url }} - if: inputs.github-packages == 'true' diff --git a/.github/workflows/coolify-deploy.yml b/.github/workflows/coolify-deploy.yml index d965a11..0e80584 100644 --- a/.github/workflows/coolify-deploy.yml +++ b/.github/workflows/coolify-deploy.yml @@ -34,9 +34,30 @@ on: type: string default: / oidc-audience: + description: >- + aud claim of the GitHub OIDC token. Pass the audience the Infisical + identity binds; the Infisical action's own default differs. required: false type: string default: "" + environment: + description: >- + GitHub environment the deploy job runs in. The OIDC token's sub + claim carries `environment:` only when the job that requests + it runs in that environment, and a caller job that uses this + workflow cannot set `environment:` itself. Empty runs the job in no + environment. + required: false + type: string + default: "" + deployment: + description: >- + With an environment, whether GitHub records a Deployment for the + job. Pass false when the caller writes its own Deployment records, + so GitHub's record of this job does not read as one of them. + required: false + type: boolean + default: true webhook-secret-name: description: Shell-safe name of the secret that holds the Coolify webhook URL. required: false @@ -80,11 +101,17 @@ permissions: jobs: deploy: runs-on: ${{ fromJSON(inputs.runner) }} + # The caller's environment, so an identity can trust one environment of + # one caller repository. GitHub builds sub from the caller repository. + environment: + name: ${{ inputs.environment }} + deployment: ${{ inputs.deployment }} timeout-minutes: ${{ inputs.timeout-minutes }} outputs: deployment-uuid: ${{ steps.webhook.outputs.deployment-uuid }} steps: - - uses: Infisical/secrets-action@v1.0.18 + # v1.0.18, pinned by commit: this step holds the deploy credentials. + - uses: Infisical/secrets-action@d2e351f16c6ca20d17c85e6c992e04bdeb64e87d with: method: oidc identity-id: ${{ inputs.infisical-identity-id }} @@ -101,7 +128,7 @@ jobs: - uses: actions/checkout@v4 with: repository: ${{ job.workflow_repository || 'PracticalWorks/.github' }} - ref: ${{ job.workflow_sha || 'v1.1.0' }} + ref: ${{ job.workflow_sha || 'v1.2.0' }} path: .pw-shared # Self-hosted runners (Proxmox ephemeral) ship without node. diff --git a/.github/workflows/pr-guard.yml b/.github/workflows/pr-guard.yml index ebe675a..58a2620 100644 --- a/.github/workflows/pr-guard.yml +++ b/.github/workflows/pr-guard.yml @@ -45,12 +45,12 @@ jobs: - uses: actions/checkout@v4 with: repository: ${{ job.workflow_repository || 'PracticalWorks/.github' }} - ref: ${{ job.workflow_sha || 'v1.1.0' }} + ref: ${{ job.workflow_sha || 'v1.2.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" + run: echo "::warning::job.workflow_sha is empty on this runner, so pr-guard ran the v1.2.0 script" # Self-hosted runners (Proxmox ephemeral) ship without node. - uses: actions/setup-node@v4 diff --git a/README.md b/README.md index 9ed87ef..1c5b537 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Consumers pin a tag: ```yaml jobs: test: - uses: PracticalWorks/.github/.github/workflows/test.yml@v1.1.0 + uses: PracticalWorks/.github/.github/workflows/test.yml@v1.2.0 ``` ## Tags @@ -16,10 +16,11 @@ jobs: | --- | --- | --- | | `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 | +| `v1.2.0` | the merge of the v1.2.0 pull request | `coolify-deploy.yml` takes `environment` (and `deployment`), so an Infisical identity can trust one GitHub environment of the caller; the setup action takes `cache` | 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. +`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.2.0` runs `v1.2.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 @@ -45,6 +46,8 @@ A called workflow can only lower the token permissions its caller grants, never Without it the workflow run fails before any step starts, because the nested job asks for a permission the caller never granted. +The setup action caches the pnpm store through `actions/setup-node` unless the caller passes `cache: false`, for example on runners that keep the store between jobs. + 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"]'`. @@ -68,20 +71,32 @@ The job goes green only when the deploy is live, not when Coolify accepts the we | `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 | +| `oidc-audience` | empty | `aud` of the GitHub OIDC token. Pass the audience the identity binds; the Infisical action's default is not ours | +| `environment` | empty | GitHub environment the deploy job runs in. See below | +| `deployment` | `true` | with `environment`, whether GitHub records a Deployment for the job. `false` for a caller that writes its own records | | `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 + uses: PracticalWorks/.github/.github/workflows/coolify-deploy.yml@v1.2.0 with: infisical-identity-id: infisical-project-slug: + oidc-audience: https://github.com/ + environment: app-prod + webhook-secret-name: COOLIFY_APP_WEBHOOK_URL health-url: https://app.example.com/health expected-version: ${{ github.sha }} ``` +### Environment + +An Infisical OIDC identity trusts a subject such as `repo:/:environment:app-prod`. The token carries `environment:` only when the job that requests it runs in that environment, and a caller job that `uses:` a workflow cannot set `environment:`. So the deploy job sets `environment.name: ${{ inputs.environment }}` itself; GitHub still builds `sub` from the caller repository. The environment's protection rules and secrets apply to the deploy job, and an environment that does not exist yet is created on the caller's first run. Leave it empty for an identity that trusts a branch or ref instead. + +A job in an environment also gets a GitHub Deployment record for the caller's commit. A caller that writes its own Deployment records in that environment passes `deployment: false`, so the job's record is not read as one of them. Custom deployment protection rules cannot be combined with `deployment: false`. + 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 diff --git a/scripts/workflows.test.mjs b/scripts/workflows.test.mjs new file mode 100644 index 0000000..cdd2142 --- /dev/null +++ b/scripts/workflows.test.mjs @@ -0,0 +1,51 @@ +// Pins the workflow and action inputs callers depend on (FACT-1910). The files +// are YAML read as text: this repository has no dependencies to parse them. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; + +const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), 'utf8'); +const deploy = read('.github/workflows/coolify-deploy.yml'); +const guard = read('.github/workflows/pr-guard.yml'); +const setup = read('.github/actions/setup/action.yml'); +const readme = read('README.md'); + +/** The block of `key:` under an inputs map, up to the next key at the same indent. */ +function input(text, key, indent) { + const pad = ' '.repeat(indent); + const start = text.indexOf(`\n${pad}${key}:\n`); + assert.ok(start >= 0, `input ${key} is declared`); + const rest = text.slice(start + 1); + const next = rest.slice(1).search(new RegExp(`\\n${pad}[A-Za-z]`)); + return next < 0 ? rest : rest.slice(0, next + 1); +} + +test('coolify-deploy takes an optional environment and runs the deploy job in it', () => { + const block = input(deploy, 'environment', 6); + assert.match(block, /required: false/); + assert.match(block, /default: ""/); + const job = deploy.slice(deploy.indexOf('\n deploy:\n')); + assert.match(job, /\n {4}environment:\n {6}name: \$\{\{ inputs\.environment \}\}\n {6}deployment: \$\{\{ inputs\.deployment \}\}\n/); + const deployment = input(deploy, 'deployment', 6); + assert.match(deployment, /type: boolean/); + assert.match(deployment, /default: true/); +}); + +test('coolify-deploy pins the Infisical action by commit', () => { + assert.match(deploy, /uses: Infisical\/secrets-action@[0-9a-f]{40}\n/); +}); + +test('the setup action caches the pnpm store unless cache is false', () => { + assert.match(input(setup, 'cache', 2), /default: "true"/); + assert.match(setup, /cache: \$\{\{ inputs\.cache == 'true' && 'pnpm' \|\| '' \}\}/); +}); + +test('each script fallback ref is the newest release in the README', () => { + const tags = [...readme.matchAll(/^\| `(v[\d.]+)` \|/gm)].map((m) => m[1]); + const newest = tags.at(-1); + for (const [name, text] of [['coolify-deploy.yml', deploy], ['pr-guard.yml', guard]]) { + const refs = [...text.matchAll(/job\.workflow_sha \|\| '([^']+)'/g)].map((m) => m[1]); + assert.ok(refs.length > 0, `${name} has a fallback ref`); + for (const ref of refs) assert.equal(ref, newest, `${name} falls back to ${newest}`); + } +});