@wtfalch/foundry 0.48.0 → 0.50.0

package/dist/plan/github-release-hook.js

@@ -0,0 +1,159 @@
+import { GITHUB_RELEASE_HOOK_COOLIFY_READ_FAILED, GITHUB_RELEASE_HOOK_ORG, GITHUB_RELEASE_HOOK_TOKEN_MISSING, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, PLATFORM_ARCHON_KEY, PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF, PLATFORM_GITHUB_RELEASE_HOOK_HASH_SCOPE_KEY, PLATFORM_GITHUB_RELEASE_HOOK_ID_SCOPE_KEY, githubReleaseHookHash, githubReleaseHookUrl, } from './platform-diff.js';
+/** Every GitHub call is cut off after this long. */
+export const GITHUB_API_TIMEOUT_MS = 20_000;
+const GITHUB_API = 'https://api.github.com';
+const PAGE_SIZE = 100;
+const MAX_PAGES = 20;
+/** A GitHub call that failed. The text is fixed: it never holds the token, the secret or a response body. */
+export class GithubApiError extends Error {
+    operation;
+    status;
+    constructor(operation, status) {
+        super(status === null
+            ? `GitHub API ${operation} did not answer`
+            : `GitHub API ${operation} failed with status ${status}`);
+        this.operation = operation;
+        this.status = status;
+        this.name = 'GithubApiError';
+    }
+}
+/** The GitHub REST organisation-hooks calls, over `fetchImpl` (global fetch by default) with a timeout on each. */
+export function createGithubHooksClient(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? GITHUB_API_TIMEOUT_MS;
+    const call = async (operation, method, path, body) => {
+        let response;
+        try {
+            response = await doFetch(`${GITHUB_API}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                    ...(body ? { 'Content-Type': 'application/json' } : {}),
+                },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            console.error(`github release hook: ${operation} did not answer (${error instanceof Error ? error.name : 'error'})`);
+            throw new GithubApiError(operation, null);
+        }
+        if (!response.ok)
+            throw new GithubApiError(operation, response.status);
+        try {
+            return await response.json();
+        }
+        catch (error) {
+            console.error(`github release hook: ${operation} answered with unreadable JSON (${error instanceof Error ? error.name : 'error'})`);
+            throw new GithubApiError(operation, response.status);
+        }
+    };
+    const asHook = (operation, value) => {
+        const hook = value;
+        if (!hook || typeof hook.id !== 'number')
+            throw new GithubApiError(operation, 200);
+        return {
+            id: hook.id,
+            active: hook.active === true,
+            events: Array.isArray(hook.events) ? hook.events.map(String) : [],
+            config: {
+                ...(typeof hook.config?.url === 'string' ? { url: hook.config.url } : {}),
+                ...(typeof hook.config?.content_type === 'string'
+                    ? { content_type: hook.config.content_type }
+                    : {}),
+            },
+        };
+    };
+    return {
+        async list(org) {
+            const hooks = [];
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const value = await call('list hooks', 'GET', `/orgs/${org}/hooks?per_page=${PAGE_SIZE}&page=${page}`);
+                if (!Array.isArray(value))
+                    throw new GithubApiError('list hooks', 200);
+                hooks.push(...value.map((v) => asHook('list hooks', v)));
+                if (value.length < PAGE_SIZE)
+                    return hooks;
+            }
+            return hooks;
+        },
+        async create(org, body) {
+            return asHook('create hook', await call('create hook', 'POST', `/orgs/${org}/hooks`, body));
+        },
+        async update(org, id, body) {
+            return asHook('update hook', await call('update hook', 'PATCH', `/orgs/${org}/hooks/${id}`, body));
+        },
+    };
+}
+async function liveWebhookSecret(deps, recorded) {
+    const appId = recorded[`coolify:app:${PLATFORM_ARCHON_KEY}`];
+    if (!appId)
+        return undefined;
+    const envs = await deps.coolify.listEnvs(appId);
+    const value = envs.find((e) => e.key === GITHUB_RELEASE_WEBHOOK_SECRET_ENV && !e.is_preview)?.value;
+    return value || undefined;
+}
+/**
+ * What the planner needs: why the step is blocked (the token is not held), or `ready` (the token is
+ * held) with the hash of the hook's url and Archon's live secret when Archon already holds one. With no
+ * secret yet the step still plans: `platform:archon` mints it earlier in the same apply.
+ */
+export async function githubReleaseHookPlanInputs(deps, hostname, recorded) {
+    const token = await deps.heldKeys.resolve(PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF);
+    if (!token)
+        return { blocked: GITHUB_RELEASE_HOOK_TOKEN_MISSING };
+    let secret;
+    try {
+        secret = await liveWebhookSecret(deps, recorded);
+    }
+    catch (error) {
+        console.error(`github release hook: could not read Archon's env from Coolify (${error instanceof Error ? error.name : 'error'})`);
+        return { blocked: GITHUB_RELEASE_HOOK_COOLIFY_READ_FAILED };
+    }
+    return secret
+        ? { ready: true, hash: githubReleaseHookHash(githubReleaseHookUrl(hostname), secret) }
+        : { ready: true };
+}
+/**
+ * Makes the organisation's release webhook. Adopts the hook whose url is Archon's, else creates one;
+ * an adopted hook is always written again, because GitHub never returns its secret.
+ *
+ * The secret is made here when Archon's app does not hold one yet (`ensureSecret`, which keeps a live
+ * value), so the step can run before `platform:archon`; that step then keeps the same value.
+ *
+ * A failure halfway: a hook made and not recorded is adopted by its url on the next run; a hook
+ * written and not recorded is written again. The id and the hash are recorded together, after the write.
+ */
+export async function provisionGithubReleaseHook(context, deps, ensureSecret) {
+    const appId = context.recordedIds()[`coolify:app:${PLATFORM_ARCHON_KEY}`];
+    if (!appId) {
+        throw new Error("platform:github-release-hook: Archon's app is not recorded yet; platform:archon runs first");
+    }
+    const token = await deps.heldKeys.resolve(PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF);
+    if (!token)
+        throw new Error(`platform:github-release-hook: ${GITHUB_RELEASE_HOOK_TOKEN_MISSING}`);
+    const secret = await ensureSecret(appId);
+    deps.onSecret?.(secret);
+    deps.onSecret?.(token);
+    const url = githubReleaseHookUrl(context.platform.archon.hostname);
+    const body = {
+        name: 'web',
+        active: true,
+        events: ['release'],
+        config: { url, content_type: 'json', secret, insecure_ssl: '0' },
+    };
+    const client = createGithubHooksClient({
+        token,
+        ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+    });
+    const existing = (await client.list(GITHUB_RELEASE_HOOK_ORG)).find((h) => h.config.url === url);
+    const hook = existing
+        ? await client.update(GITHUB_RELEASE_HOOK_ORG, existing.id, body)
+        : await client.create(GITHUB_RELEASE_HOOK_ORG, body);
+    context.recordScopeId(PLATFORM_GITHUB_RELEASE_HOOK_ID_SCOPE_KEY, String(hook.id));
+    context.recordScopeId(PLATFORM_GITHUB_RELEASE_HOOK_HASH_SCOPE_KEY, githubReleaseHookHash(url, secret));
+    await context.persist?.();
+    return undefined;
+}

package/dist/plan/index.d.ts

@@ -5,7 +5,7 @@ export { computePlanDetail, toPlan } from './diff.js';
 export type { StepSystem } from './step-system.js';
 export { stepSystemOf } from './step-system.js';
 export type { PlatformPlanDetail, MailRoute } from './platform-diff.js';
-export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, GITHUB_RELEASE_HOOK_ORG, GITHUB_RELEASE_HOOK_PATH, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, } from './platform-diff.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './platform-org.js';
 export type { PlanOwnAuthOptions, PlanOwnFilesOptions, PlanOwnFilesR2Options, PlanOwnJobsOptions, } from './own-diff.js';
@@ -41,6 +41,11 @@ export { createZitadelOrgMetadata } from './zitadel-org-metadata.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export { DumpError, dumpNow } from './database-dump.js';
 export type { DatabaseDump } from './database-dump.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, STAGE_SINK_SMTP_PORT, stageMailEnv, stageSinkAppName, stageSinkInternalUrl, } from './stage-sink.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './stage-copy.js';
+export type { StageCopyInput, StageCopyPort, StageCopyProduction, StageCopyRefusalReason, StageCopyRunRecord, UndoStageCopyInput, } from './stage-copy.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './stage-copy-port.js';
+export type { Runner, StageCopyPortDeps } from './stage-copy-port.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';
@@ -70,6 +75,7 @@ export { createEdgeAccess } from './edge-access.js';
 export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, EdgePlatformAccess, } from './edge-access.js';
 export { createEdgeWorkers } from './edge-workers.js';
 export type { EdgePlatformWorkers, EdgeWorkersOptions, PlatformWorkersPort, } from './edge-workers.js';
+export type { PlatformGithubReleaseHookDeps } from './github-release-hook.js';
 export type { PlatformUptimeAccessFactory, PlatformUptimeAccessPort, PlatformUptimeChatDeps, PlatformUptimeDeps, PlatformWorkersFactory, } from './uptime-worker.js';
 export { createEdgeRateLimits } from './edge-ratelimits.js';
 export type { EdgePlatformRateLimits, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, } from './edge-ratelimits.js';

package/dist/plan/index.js

@@ -1,7 +1,7 @@
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export { stepSystemOf } from './step-system.js';
-export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_RELAY_KEY, PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_EDGE_KEY_REF, PLATFORM_EDGE_CLOUDFLARE_TOKEN_REF, GITHUB_RELEASE_HOOK_ORG, GITHUB_RELEASE_HOOK_PATH, GITHUB_RELEASE_WEBHOOK_SECRET_ENV, PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF, PLATFORM_SFU_APPLIED_SCOPE_KEY, } from './platform-diff.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './platform-org.js';
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, } from './own-diff.js';
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu } from './own-diff.js';
@@ -26,6 +26,9 @@ export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 // implements over held keys and its own SSH client, the same shape the rest
 // of `platform-providers.ts` uses for Cloudflare.
 export { DumpError, dumpNow } from './database-dump.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, STAGE_SINK_SMTP_PORT, stageMailEnv, stageSinkAppName, stageSinkInternalUrl, } from './stage-sink.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './stage-copy.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './stage-copy-port.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';

package/dist/plan/live.d.ts

@@ -42,7 +42,7 @@ export interface LiveResource {
      * see that function's own doc comment for why "always planned" broke
      * `bootstrapPlatform`.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github';
     kind: string;
     key: string;
     config: Record<string, unknown>;

package/dist/plan/plan-apply.d.ts

@@ -219,6 +219,8 @@ export interface StepExecutor {
         usable: boolean;
         reachable: boolean;
     }>>;
+    /** Whether the company's stage mail sink app (by Coolify id) is stopped or gone, read live. Optional: an executor without it reads the sink as up. */
+    stageSinkDown?(appId: string): Promise<boolean>;
     /**
      * The release runner's outside calls for one blue/green entry (`plan/release-host.ts`); `null` while its blue
      * copy is not recorded. Optional: an executor without it runs no release.

package/dist/plan/plan-apply.js

@@ -1313,6 +1313,10 @@ export class FoundryPlanApply {
         const blueGreenServers = declaresBlueGreen(org) && this.executor.blueGreenServers
             ? await this.executor.blueGreenServers().catch(() => undefined)
             : undefined;
+        const sinkId = recorded.stage_sink_app;
+        const stageSinkDown = sinkId && recorded.stage_sink_applied && declaresBlueGreen(org) && this.executor.stageSinkDown
+            ? await this.executor.stageSinkDown(sinkId).catch(() => false)
+            : false;
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
             loginHostBindings: this.loginHostBindings,
             loginHostClientOrganizations: this.loginHostClientOrganizations,
@@ -1343,6 +1347,7 @@ export class FoundryPlanApply {
             customersDirectory: this.executor.customersDirectoryAvailable?.() ?? false,
             bouleArchonCredential: this.executor.bouleArchonCredentialAvailable?.() ?? false,
             ...(blueGreenServers ? { blueGreenServers } : {}),
+            ...(stageSinkDown ? { stageSinkDown } : {}),
             ...(blueGreenServers && org.hosting.entries.some((e) => e.blueGreen && e.database)
                 ? {
                     remoteDatabase: remoteDatabaseFactsFrom({
@@ -2137,9 +2142,9 @@ function destroyStepDescriptions(targets) {
         'delete the declared org',
     ];
 }
-/** Scope keys of the Coolify apps blue/green made: `bg.<entry>.app.<server>.<part>`, a database sidecar, a connector on another server. */
-const BLUE_GREEN_APP_KEY = /^(bg\.[^.:]+\.app\.[^.:]+\.[a-z]+|bgdb\.[^.:]+\.sidecar\.[^.:]+|cloudflare_tunnel_connector_app\.[^.:]+)$/;
-const BLUE_GREEN_DATABASE_KEY = /^bg\.[^.:]+\.stagedb$/;
+/** Scope keys of the Coolify apps blue/green made: `bg.<entry>.app.<server>.<part>`, a database sidecar, a connector on another server, the company's stage mail sink (`stage_sink_app`). */
+const BLUE_GREEN_APP_KEY = /^(bg\.[^.:]+\.app\.[^.:]+\.[a-z]+|bgdb\.[^.:]+\.sidecar\.[^.:]+|cloudflare_tunnel_connector_app\.[^.:]+|stage_sink_app)$/;
+const BLUE_GREEN_DATABASE_KEY = /^bg\.[^.:]+\.(stagedb|stagekept)$/;
 /** Stage's Access gate (`bg.<entry>.stagegate`), and the database route's Cloudflare parts: its Access app, its service token (also one minted and never delivered) and its DNS record (recorded as the route). */
 const BLUE_GREEN_EDGE_KEYS = [
     [/^bgdb\.[^.:]+\.access$/, 'bg-access'],

package/dist/plan/platform-diff.d.ts

@@ -151,6 +151,13 @@ export declare const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = "archon
  * values until someone redeploys by hand (#467).
  */
 export declare const PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY = "archon_envs_deployed_hash";
+/**
+ * The sha256 of the `GITHUB_RELEASE_WEBHOOK_SECRET` Archon last deployed with, recorded by
+ * `platform:archon` after its deploy (never the secret). `driftedSteps` plans `platform:archon` again
+ * while the live secret is missing or hashes differently: the release hook step writes the secret into
+ * Coolify and nothing else redeploys an applied Archon.
+ */
+export declare const PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY = "archon_webhook_secret_deployed_sha256";
 /**
  * The uuid of the deployment Archon's step triggered without waiting
  * (`PlatformArchonDeps.runsInsideApp`), `pending` between the trigger and the
@@ -412,6 +419,29 @@ export declare const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = "platform:mas
  * already holds the same panel's address.
  */
 export declare const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = "platform:archon:coolify-read-token";
+/**
+ * The held key (tenant `platform`) of a fine-grained GitHub token for the `wtfalch`
+ * organisation with Webhooks read and write. Foundry only reads it back; a person holds it in
+ * Archon, Shared, Keys. Until it is held, the `platform:github-release-hook` step is reported
+ * blocked and nothing else is.
+ */
+export declare const PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF = "platform:github:org-hooks-token";
+/** Archon's env name for the secret GitHub signs release webhooks with. Minted once by `platform:archon`, never rotated. */
+export declare const GITHUB_RELEASE_WEBHOOK_SECRET_ENV = "GITHUB_RELEASE_WEBHOOK_SECRET";
+/** The GitHub organisation whose release webhook `platform:github-release-hook` makes. */
+export declare const GITHUB_RELEASE_HOOK_ORG = "wtfalch";
+/** Archon's route that takes release webhooks, under its public host. */
+export declare const GITHUB_RELEASE_HOOK_PATH = "/api/github/releases";
+/** The step key. */
+export declare const PLATFORM_GITHUB_RELEASE_HOOK_KEY = "platform:github-release-hook";
+/** Scope key: the id of the organisation hook the step made or adopted. */
+export declare const PLATFORM_GITHUB_RELEASE_HOOK_ID_SCOPE_KEY = "github_release_hook_id";
+/** Scope key: the hash of the hook's url and secret as last written. The secret itself is never recorded. */
+export declare const PLATFORM_GITHUB_RELEASE_HOOK_HASH_SCOPE_KEY = "github_release_hook_hash";
+/** Why the step is blocked while Archon's env cannot be read from Coolify. */
+export declare const GITHUB_RELEASE_HOOK_COOLIFY_READ_FAILED = "the GitHub release webhook is blocked, not planned: could not read Archon's env from Coolify";
+/** Why the step is blocked while the token is not held. */
+export declare const GITHUB_RELEASE_HOOK_TOKEN_MISSING = "the GitHub release webhook is blocked, not planned: hold the GitHub organisation webhooks token in Archon, Shared, Keys";
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -1248,6 +1278,14 @@ export interface PlanPlatformOptions {
             pending: boolean;
             blocked?: string;
         };
+        /** Why the organisation's release webhook step cannot run (the token is not held), or absent. */
+        githubReleaseHook?: string;
+        /**
+         * The token is held: the step may plan, also in the apply that makes Archon.
+         */
+        githubReleaseHookReady?: boolean;
+        /** The hash of the hook's url and Archon's live webhook secret now (`githubReleaseHookHash`). Absent while Archon holds no secret. */
+        githubReleaseHookHash?: string;
         /** Why Archon's step must wait: the deployment it triggered is still running. Blocks even an applied step. */
         archonDeployRunning?: string;
         /**
@@ -1448,6 +1486,27 @@ export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = "in
  * `''`) as soon as the mint is recorded, so one request is one rotation.
  */
 export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = "integrations_management_key_rotation_requested";
+/**
+ * foundry#542: the uptime Worker, one `cloudflare:worker` step. Blocked, not
+ * planned (rule 2), while no artifact is pinned, Archon is not applied, the
+ * executor lacks its dependencies, a Worker or Access token of the name exists
+ * that foundry did not make. A lost Worker token or Access pair is not a
+ * block: the step is planned and repairs it (rule 4). Planned again when the
+ * pinned tag or sha256, the Archon hostname (`ARCHON_BASE_URL`), the plain
+ * text variables or the set of secrets that can be set changed (rule 3), or
+ * when a half-made deploy never recorded its applied values; it mints nothing
+ * that is already held. When the platform no longer enables the Worker, a
+ * destructive step removes whatever of it is recorded (edge removes its KV
+ * namespace with the script).
+ *
+ * The returned `blocked` lines are reported in `unmanaged`. A secret whose
+ * source does not exist yet blocks nothing: the step still delivers
+ * everything that exists, so it comes back in `notes`.
+ */
+/** The hash of a hook's url and secret. The planner and the step both compute it, and it is the only trace of the secret that is recorded. */
+export declare function githubReleaseHookHash(url: string, secret: string): string;
+/** The url GitHub delivers release webhooks to. */
+export declare function githubReleaseHookUrl(hostname: string): string;
 /**
  * #175: Archon (https://github.com/wtfalch/archon), the one shared console,
  * built fresh at `platform.archon.hostname` (`archon.<apex>`) rather than the

package/dist/plan/platform-diff.js

@@ -190,6 +190,13 @@ export const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = 'archon_integra
  * values until someone redeploys by hand (#467).
  */
 export const PLATFORM_ARCHON_ENVS_DEPLOYED_SCOPE_KEY = 'archon_envs_deployed_hash';
+/**
+ * The sha256 of the `GITHUB_RELEASE_WEBHOOK_SECRET` Archon last deployed with, recorded by
+ * `platform:archon` after its deploy (never the secret). `driftedSteps` plans `platform:archon` again
+ * while the live secret is missing or hashes differently: the release hook step writes the secret into
+ * Coolify and nothing else redeploys an applied Archon.
+ */
+export const PLATFORM_ARCHON_WEBHOOK_SECRET_DEPLOYED_SCOPE_KEY = 'archon_webhook_secret_deployed_sha256';
 /**
  * The uuid of the deployment Archon's step triggered without waiting
  * (`PlatformArchonDeps.runsInsideApp`), `pending` between the trigger and the
@@ -464,6 +471,29 @@ export const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = 'platform:master:clou
  * already holds the same panel's address.
  */
 export const PLATFORM_ARCHON_COOLIFY_READ_TOKEN_REF = 'platform:archon:coolify-read-token';
+/**
+ * The held key (tenant `platform`) of a fine-grained GitHub token for the `wtfalch`
+ * organisation with Webhooks read and write. Foundry only reads it back; a person holds it in
+ * Archon, Shared, Keys. Until it is held, the `platform:github-release-hook` step is reported
+ * blocked and nothing else is.
+ */
+export const PLATFORM_GITHUB_ORG_HOOKS_TOKEN_REF = 'platform:github:org-hooks-token';
+/** Archon's env name for the secret GitHub signs release webhooks with. Minted once by `platform:archon`, never rotated. */
+export const GITHUB_RELEASE_WEBHOOK_SECRET_ENV = 'GITHUB_RELEASE_WEBHOOK_SECRET';
+/** The GitHub organisation whose release webhook `platform:github-release-hook` makes. */
+export const GITHUB_RELEASE_HOOK_ORG = 'wtfalch';
+/** Archon's route that takes release webhooks, under its public host. */
+export const GITHUB_RELEASE_HOOK_PATH = '/api/github/releases';
+/** The step key. */
+export const PLATFORM_GITHUB_RELEASE_HOOK_KEY = 'platform:github-release-hook';
+/** Scope key: the id of the organisation hook the step made or adopted. */
+export const PLATFORM_GITHUB_RELEASE_HOOK_ID_SCOPE_KEY = 'github_release_hook_id';
+/** Scope key: the hash of the hook's url and secret as last written. The secret itself is never recorded. */
+export const PLATFORM_GITHUB_RELEASE_HOOK_HASH_SCOPE_KEY = 'github_release_hook_hash';
+/** Why the step is blocked while Archon's env cannot be read from Coolify. */
+export const GITHUB_RELEASE_HOOK_COOLIFY_READ_FAILED = "the GitHub release webhook is blocked, not planned: could not read Archon's env from Coolify";
+/** Why the step is blocked while the token is not held. */
+export const GITHUB_RELEASE_HOOK_TOKEN_MISSING = 'the GitHub release webhook is blocked, not planned: hold the GitHub organisation webhooks token in Archon, Shared, Keys';
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -1441,8 +1471,25 @@ export function planPlatform(platform, live, options = {}) {
             step: { description: archonBg.step.description, destroys: false, migrates: false },
         });
     }
-    if (archon.step && blocked.archonRunsInsideApp)
+    let releaseHook;
+    // The hook step makes the secret itself, so with the app recorded it goes before a last-placed
+    // platform:archon (the host redeploys itself there and would stop before a later step). Without the
+    // app it goes after platform:archon, which makes the app.
+    if (archon.step && blocked.archonRunsInsideApp) {
+        const hookFirst = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_ARCHON_KEY)]);
+        const hookStep = () => planGithubReleaseHook(platform, recordedIds, blocked.githubReleaseHook, blocked.githubReleaseHookReady ?? false, blocked.githubReleaseHookHash, true);
+        releaseHook = hookStep();
+        if (hookFirst && releaseHook.step)
+            plannedSteps.push(releaseHook.step);
         plannedSteps.push(archon.step);
+        if (!hookFirst && releaseHook.step)
+            plannedSteps.push(releaseHook.step);
+    }
+    else {
+        releaseHook = planGithubReleaseHook(platform, recordedIds, blocked.githubReleaseHook, blocked.githubReleaseHookReady ?? false, blocked.githubReleaseHookHash, Boolean(archon.step));
+        if (releaseHook.step)
+            plannedSteps.push(releaseHook.step);
+    }
     // After Archon's own step: a repair that fails must not hold up the work before it.
     const idTokenUserinfo = planArchonIdTokenUserinfo(platform, recordedIds, blocked.archonIdTokenUserinfo ?? false);
     if (idTokenUserinfo)
@@ -1575,6 +1622,9 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: heartbeats.blocked, key: 'heartbeats' });
     for (const description of uptime.blocked)
         unmanaged.push({ description, key: 'uptime' });
+    if (releaseHook.blocked) {
+        unmanaged.push({ description: releaseHook.blocked, key: 'github-release-hook' });
+    }
     return {
         plannedSteps: plannedSteps.map(withStepSystem),
         unmanaged,
@@ -2932,6 +2982,53 @@ function planHeartbeats(platform, recordedIds, hcReady, executorMissing, apiKeyM
  * source does not exist yet blocks nothing: the step still delivers
  * everything that exists, so it comes back in `notes`.
  */
+/** The hash of a hook's url and secret. The planner and the step both compute it, and it is the only trace of the secret that is recorded. */
+export function githubReleaseHookHash(url, secret) {
+    return createHash('sha256').update(`${url}\n${secret}`).digest('hex');
+}
+/** The url GitHub delivers release webhooks to. */
+export function githubReleaseHookUrl(hostname) {
+    return `https://${hostname}${GITHUB_RELEASE_HOOK_PATH}`;
+}
+/**
+ * The organisation's release webhook, once the token is held and Archon is applied or planned in this
+ * same plan (`platform:archon` runs first and mints the secret). Planned when no hook is recorded, or the
+ * recorded hash of (url, secret) differs from the one now.
+ * Blocked, not planned, while the token is not held; nothing else is held back by that.
+ */
+function planGithubReleaseHook(platform, recordedIds, executorBlocked, tokenHeld, currentHash, archonPlanned) {
+    if (!platform.archon.enabled)
+        return { step: null, blocked: null };
+    if (!recordedIds[resourceKey('coolify', 'app', PLATFORM_ARCHON_KEY)] && !archonPlanned) {
+        return { step: null, blocked: null };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: executorBlocked };
+    if (!tokenHeld)
+        return { step: null, blocked: null };
+    if (currentHash &&
+        recordedIds[PLATFORM_GITHUB_RELEASE_HOOK_ID_SCOPE_KEY] &&
+        recordedIds[PLATFORM_GITHUB_RELEASE_HOOK_HASH_SCOPE_KEY] === currentHash) {
+        return { step: null, blocked: null };
+    }
+    const url = githubReleaseHookUrl(platform.archon.hostname);
+    return {
+        step: {
+            action: {
+                system: 'github',
+                kind: 'release-hook',
+                key: PLATFORM_GITHUB_RELEASE_HOOK_KEY,
+                desired: { org: GITHUB_RELEASE_HOOK_ORG, url, events: ['release'] },
+            },
+            step: {
+                description: `make the ${GITHUB_RELEASE_HOOK_ORG} organisation's release webhook to ${url}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 function planUptime(platform, recordedIds, executorBlocked, heldOptional, archonApplied, uptimeHeld = {
     token: true,
     access: true,

package/dist/plan/platform-providers.d.ts

@@ -21,6 +21,7 @@ import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platf
 import type { PlatformOwnerInput } from './platform-org.js';
 import type { SigninDbBackupPort } from './signin-db-backup.js';
 export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
+import { type PlatformGithubReleaseHookDeps } from './github-release-hook.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 import { type PlatformUptimeDeps } from './uptime-worker.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
@@ -324,6 +325,11 @@ export interface FoundryPlatformStepExecutorOptions {
      * unset, the step is reported blocked.
      */
     oikosIngress?: PlatformOikosIngressDeps;
+    /**
+     * The `github:release-hook` step. Optional like `auth`; without it the step is not planned and
+     * nothing is reported.
+     */
+    githubReleaseHook?: PlatformGithubReleaseHookDeps;
 }
 export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor {
     private readonly cloudflare;
@@ -345,6 +351,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly uptime?;
     private readonly accessProvider?;
     private readonly oikosIngress?;
+    private readonly githubReleaseHook?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list' | 'get'>, options?: FoundryPlatformStepExecutorOptions);
     private readonly platformPorts;
     /** The port placed on the platform's destination, made once per port so a server is listed once. */
@@ -388,6 +395,9 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
             pending: boolean;
             blocked?: string;
         };
+        githubReleaseHook?: string;
+        githubReleaseHookReady?: boolean;
+        githubReleaseHookHash?: string;
         archonRunsInsideApp?: boolean;
         archonDeployRunning?: string;
         archonIdTokenUserinfo?: boolean;