Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion .github/actions/setup/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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'
Expand Down
31 changes: 29 additions & 2 deletions .github/workflows/coolify-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:<name>` 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
Expand Down Expand Up @@ -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 }}
Expand All @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/pr-guard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 18 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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"]'`.
Expand All @@ -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: <identity id>
infisical-project-slug: <project slug>
oidc-audience: https://github.com/<org>
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:<org>/<repo>:environment:app-prod`. The token carries `environment:<name>` 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
Expand Down
51 changes: 51 additions & 0 deletions scripts/workflows.test.mjs
Original file line number Diff line number Diff line change
@@ -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}`);
}
});
Loading