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
32 changes: 31 additions & 1 deletion .github/workflows/coolify-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,24 @@ on:
required: false
type: string
default: ""
wait:
description: >-
Whether the job waits for Coolify's outcome (and health-url). false
posts the webhook, outputs the deployment uuid and exits, so the
caller pays for seconds, not for the wait; something off the runner
must then watch the deployment (FACT-2001).
required: false
type: boolean
default: true
pre-deploy-run:
description: >-
Optional shell run in a checkout of the caller's commit after the
Infisical secrets are exported and Node is set up, before the
webhook. Folds a step such as an env sync into this job instead of
a separate job with its own one-minute minimum (FACT-2001).
required: false
type: string
default: ""
outputs:
deployment-uuid:
description: Coolify deployment uuid from the webhook response.
Expand Down Expand Up @@ -122,20 +140,31 @@ jobs:
secret-path: ${{ inputs.infisical-secret-path }}
export-type: env

# The caller's commit, for pre-deploy-run. Before the shared checkout,
# which it would otherwise clean away.
- if: inputs.pre-deploy-run != ''
uses: actions/checkout@v4

# 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.2.0' }}
ref: ${{ job.workflow_sha || 'v1.3.0' }}
path: .pw-shared

# Self-hosted runners (Proxmox ephemeral) ship without node.
- uses: actions/setup-node@v4
with:
node-version: 22

- if: inputs.pre-deploy-run != ''
name: Pre-deploy
env:
PRE_DEPLOY_RUN: ${{ inputs.pre-deploy-run }}
run: bash -euo pipefail -c "$PRE_DEPLOY_RUN"

- id: webhook
name: Deploy on Coolify and prove it is live
env:
Expand All @@ -144,6 +173,7 @@ jobs:
HEALTH_URL: ${{ inputs.health-url }}
EXPECTED_VERSION: ${{ inputs.expected-version }}
TIMEOUT_MINUTES: ${{ inputs.timeout-minutes }}
WAIT: ${{ inputs.wait }}
run: |
set -euo pipefail
# Mask both values before anything can print them. printenv does
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.2.0' }}
ref: ${{ job.workflow_sha || 'v1.3.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.2.0 script"
run: echo "::warning::job.workflow_sha is empty on this runner, so pr-guard ran the v1.3.0 script"

# Self-hosted runners (Proxmox ephemeral) ship without node.
- uses: actions/setup-node@v4
Expand Down
7 changes: 5 additions & 2 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.2.0
uses: PracticalWorks/.github/.github/workflows/test.yml@v1.3.0
```

## Tags
Expand All @@ -17,6 +17,7 @@ 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` |
| `v1.3.0` | the merge of the v1.3.0 pull request | `coolify-deploy.yml` takes `wait` (false: post the webhook and exit, so the caller is billed seconds, not the wait) and `pre-deploy-run` (a shell step in the caller's checkout before the webhook, e.g. an env sync, instead of a separate job) |

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`.

Expand Down Expand Up @@ -74,13 +75,15 @@ The job goes green only when the deploy is live, not when Coolify accepts the we
| `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 |
| `wait` | `true` | `false` posts the webhook, outputs `deployment-uuid` and exits. Something off the runner must then watch the deployment; `health-url` is refused with it |
| `pre-deploy-run` | empty | shell run in a checkout of the caller's commit, after the Infisical secrets are exported and Node 22 is set up, before the webhook |
| `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.2.0
uses: PracticalWorks/.github/.github/workflows/coolify-deploy.yml@v1.3.0
with:
infisical-identity-id: <identity id>
infisical-project-slug: <project slug>
Expand Down
10 changes: 10 additions & 0 deletions scripts/coolify-deploy.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ export async function deployAndProve({
token,
healthUrl = "",
expectedVersion = "",
wait = true,
timeoutMs,
setOutput = () => {},
...io
Expand All @@ -153,11 +154,19 @@ export async function deployAndProve({
if (Boolean(healthUrl) !== Boolean(expectedVersion)) {
throw new Error("health-url and expected-version go together: pass both or neither");
}
if (!wait && healthUrl) {
throw new Error("health-url needs wait: a deploy that does not wait never polls it");
}
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`);
if (!wait) {
// The caller pays per minute of runner; the wait is watched off the runner (FACT-2001).
(io.log ?? console.log)(`not waiting: deployment ${uuid} is confirmed off the runner`);
return uuid;
}
await waitForDeployment({ ...io, base: coolifyBase(webhookUrl), token, uuid, deadline });
if (healthUrl) await waitForVersion({ ...io, healthUrl, expectedVersion, deadline });
return uuid;
Expand Down Expand Up @@ -185,6 +194,7 @@ async function main() {
token,
healthUrl: env.HEALTH_URL ?? "",
expectedVersion: env.EXPECTED_VERSION ?? "",
wait: env.WAIT !== "false",
timeoutMs: budgetMs(env.TIMEOUT_MINUTES),
setOutput: (uuid) => {
if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `deployment-uuid=${uuid}\n`);
Expand Down
34 changes: 34 additions & 0 deletions scripts/coolify-deploy.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -173,3 +173,37 @@ test("the poll budget leaves a minute of the job timeout", () => {
assert.equal(budgetMs(1), 60_000);
assert.equal(budgetMs(""), 9 * 60_000);
});

test("wait false posts the webhook, outputs the uuid and never polls (FACT-2001)", async () => {
const { fetchImpl, calls } = fakeFetch({
[POST]: [respond(200, { deployments: [{ deployment_uuid: "dep-1" }] })],
});
const outputs = [];
const uuid = await deployAndProve({
webhookUrl: WEBHOOK,
token: TOKEN,
wait: false,
timeoutMs: 600_000,
setOutput: (u) => outputs.push(u),
fetchImpl,
...clock(),
log: () => {},
});
assert.equal(uuid, "dep-1");
assert.deepEqual(outputs, ["dep-1"]);
assert.deepEqual(calls.map((c) => c.key), [POST]);
});

test("wait false refuses a health URL it would never poll", async () => {
await assert.rejects(
deployAndProve({
webhookUrl: WEBHOOK,
token: TOKEN,
wait: false,
healthUrl: "https://app.example.test/health",
expectedVersion: "abc",
timeoutMs: 1,
}),
/health-url needs wait/,
);
});
15 changes: 15 additions & 0 deletions scripts/workflows.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,18 @@ test('each script fallback ref is the newest release in the README', () => {
for (const ref of refs) assert.equal(ref, newest, `${name} falls back to ${newest}`);
}
});

test('coolify-deploy can skip the wait and run a pre-deploy step in the caller checkout (FACT-2001)', () => {
const wait = input(deploy, 'wait', 6);
assert.match(wait, /type: boolean/);
assert.match(wait, /default: true/);
assert.match(input(deploy, 'pre-deploy-run', 6), /default: ""/);
assert.match(deploy, /WAIT: \$\{\{ inputs\.wait \}\}/);
// The caller checkout comes before the shared one, which it would otherwise clean away.
const caller = deploy.indexOf("- if: inputs.pre-deploy-run != ''\n uses: actions/checkout@v4");
const shared = deploy.indexOf('path: .pw-shared');
assert.ok(caller >= 0 && caller < shared, 'caller checkout precedes the shared checkout');
// The pre-deploy step runs after the secrets and node, before the webhook.
const pre = deploy.indexOf('name: Pre-deploy');
assert.ok(pre > deploy.indexOf('Infisical/secrets-action') && pre > deploy.indexOf('actions/setup-node') && pre < deploy.indexOf('id: webhook'));
});
Loading