@olivervea/pipelines 2.0.0-beta.3 → 2.0.0-beta.7

package/src/describe/manifest-schema.ts

@@ -7,6 +7,7 @@ export const API_VERSION = "2.0";
 const stepName = z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/).describe("Step name: lower-case kebab, 1-63 chars. The step's identity.");
 const modelName = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Model name (key of `models`).");
 const secretName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/).describe("Secret name; also the env var name in the step container.");
+const configName = z.string().regex(/^[a-z][a-zA-Z0-9]*$/).describe("Config entry name; a key of the pipeline's config document.");
 const hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
 const Json = z.json().meta({ id: "Json", description: "Any JSON value." });
 const jsonSchema = z.record(z.string(), z.unknown()).describe("A JSON Schema (draft 2020-12) object, canonical (sorted keys, no $schema).");
@@ -50,7 +51,7 @@ export const StepDescriptor = z
   .strictObject({
     name: stepName,
     description: z.string().describe("What the step does, shown in the UI (may be empty)."),
-    kind: z.enum(["custom", "script", "gitHubSource", "imageBuild", "helmDeployOverSsh"]).describe("'custom' = handlers/<name>.ts; others are SDK library steps."),
+    kind: z.string().min(1).describe("'custom' = handlers/<name>.ts; others are SDK library steps. A label: the service accepts any kind."),
     image: z.string().min(1).describe("Container image the step runs in."),
     inputTypes: z.record(z.string(), InputType).describe("Declared input entries, keyed like input.json."),
     input: z.record(z.string(), Mapping).describe("How the service assembles input.json: one mapping per input key (same keys as inputTypes)."),
@@ -59,11 +60,25 @@ export const StepDescriptor = z
     handlerHash: hash.describe("Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for library steps kind + config + harness."),
     timeoutSeconds: z.number().int().positive().optional(),
     retries: z.number().int().nonnegative().optional(),
-    config: z.record(z.string(), Json).optional().describe("Library-step configuration (display only; already covered by handlerHash)."),
+    config: z
+      .record(z.string(), Json)
+      .optional()
+      .describe("Library-step configuration (display only; already covered by handlerHash). A config reference is recorded as {\"$config\": \"<entry>.<field>…\"}; the entry is in configEntries."),
+    configEntries: z
+      .array(configName)
+      .optional()
+      .describe("Config entries the step receives (sorted; omitted when none). The service delivers them in input.json under '$config'."),
+    clusterAccess: z
+      .literal(true)
+      .optional()
+      .describe("The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token."),
   })
   .meta({ id: "Step" });
 
-export type Stage = { steps: z.infer<typeof StepDescriptor>[] } | { when: Record<string, (string | number | boolean)[]>; stages: Stage[] };
+export type Stage =
+  | { steps: z.infer<typeof StepDescriptor>[] }
+  | { when: Record<string, (string | number | boolean)[]>; stages: Stage[] }
+  | { select: string; discriminator: string; cases: Record<string, Stage[]> };
 export const Stage: z.ZodType<Stage> = z
   .union([
     z.strictObject({ steps: z.array(StepDescriptor).min(1).describe("Steps run in parallel; the stage is a barrier.") }),
@@ -73,6 +88,13 @@ export const Stage: z.ZodType<Stage> = z
       ),
       stages: z.array(z.lazy(() => Stage)),
     }),
+    z.strictObject({
+      select: z.string().min(1).describe("Config reference (`<entry>.<field>…`) to a discriminated union; the run's config snapshot picks the case."),
+      discriminator: z.string().min(1).describe("The union's literal field whose value names the case."),
+      cases: z
+        .record(z.string(), z.array(z.lazy(() => Stage)))
+        .describe("Discriminator value → stages. Exactly one case runs; a step name may repeat across cases, nowhere else."),
+    }),
   ])
   .meta({ id: "Stage" });
 
@@ -123,6 +145,17 @@ export const Manifest = z
       .describe("Harness identity. Already folded into every handlerHash."),
     models: z.record(modelName, ModelSchemas).describe("Every model referenced by the pipeline (input, step inputs/outputs)."),
     secrets: z.array(z.strictObject({ name: secretName, description: z.string() })).describe("All declared secrets (steps + poll triggers), sorted by name."),
+    config: z
+      .array(
+        z.strictObject({
+          name: configName,
+          description: z.string(),
+          required: z.boolean().describe("False when the schema accepts a missing value (optional, or a default)."),
+          schema: jsonSchema.describe("z.input view: validates the config document's value for this entry (defaults listed)."),
+        }),
+      )
+      .optional()
+      .describe("Config entries used by steps, sorted by name (omitted when none). Fields of kind secretRef ({secret: NAME}) name a secret."),
     triggers: z.array(Trigger),
     stages: z.array(Stage),
     failureHandlers: z.array(

package/src/dev/cli.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 // olve-dev — run a pipeline from source through the same harness path as the compiled binary.
 //   olve-dev describe <dir> [--sentinels]
-//   olve-dev run <dir> <step> [--input-file f] [--olve-dir d] [--secret NAME=value]...
+//   olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
 //   olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
 // $OLVE_DIR defaults to <dir>/.olve; outputs land in <dir>/.olve/work/.
-import { copyFileSync, mkdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { runHarness, type HarnessConfig } from "../harness/main.ts";
@@ -13,7 +13,7 @@ import { handlerHashes } from "../build/hashes.ts";
 import { harnessInfo, loadProject, ProjectError } from "../build/project.ts";
 
 const USAGE = `usage: olve-dev describe <dir> [--sentinels]
-       olve-dev run <dir> <step> [--input-file f] [--olve-dir d] [--secret NAME=value]...
+       olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
        olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]`;
 
 export async function devConfig(dir: string, withHashes: boolean): Promise<HarnessConfig> {
@@ -38,6 +38,7 @@ export async function devMain(argv: string[]): Promise<number> {
       allowPositionals: true,
       options: {
         "input-file": { type: "string" },
+        "config-file": { type: "string" },
         "event-file": { type: "string" },
         "olve-dir": { type: "string" },
         secret: { type: "string", multiple: true },
@@ -68,6 +69,12 @@ export async function devMain(argv: string[]): Promise<number> {
     }
     const file = mode === "run" ? values["input-file"] : values["event-file"];
     if (file) copyFileSync(resolve(file), join(olveDir, "input.json"));
+    if (mode === "run" && values["config-file"]) {
+      const inputFile = join(olveDir, "input.json");
+      const input = (existsSync(inputFile) ? JSON.parse(readFileSync(inputFile, "utf8")) : {}) as Record<string, unknown>;
+      input.$config = JSON.parse(readFileSync(resolve(values["config-file"]), "utf8"));
+      writeFileSync(inputFile, JSON.stringify(input));
+    }
     else if (mode === "map-trigger") return console.error("--event-file is required"), EXIT.usage;
     return await runHarness(await devConfig(dir, false), [mode, name]);
   } catch (e) {

package/src/harness/execute.ts

@@ -8,7 +8,7 @@ import type { Ctx, RunInfo } from "../ctx/types.ts";
 import { objectPath } from "../ctx/files.ts";
 import { sha256File } from "../util/hash.ts";
 import { EXIT } from "./exit.ts";
-import { validateInput, validateOutput } from "./validate.ts";
+import { validateConfig, validateInput, validateOutput } from "./validate.ts";
 
 export type FailureKind = "handler" | "input" | "output";
 export type Envelope =
@@ -58,13 +58,16 @@ export async function executeStep(args: {
   workFiles: string;
   log: (line: string) => void;
 }): Promise<Execution> {
-  const { step, ctx, log } = args;
+  const { step, log } = args;
   const input = validateInput(step, args.rawInput);
-  if (!input.ok) {
-    const message = `step '${step.name}': input does not match the step's inputs:\n  ${input.issues.join("\n  ")}`;
+  const config = validateConfig(step, args.rawInput);
+  if (!input.ok || !config.ok) {
+    const issues = [...(input.ok ? [] : input.issues), ...(config.ok ? [] : config.issues)];
+    const message = `step '${step.name}': input does not match the step's inputs:\n  ${issues.join("\n  ")}`;
     log(message);
     return { envelope: { status: "failed", error: { kind: "input", message } }, exitCode: EXIT.inputInvalid };
   }
+  const ctx: Ctx = { ...args.ctx, config: Object.freeze(config.value) as Ctx["config"] };
 
   let value: unknown;
   try {

package/src/harness/main.ts

@@ -5,6 +5,7 @@
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isImplementation } from "../core/handlers.ts";
+import { configRefPath, isConfigRef, unionAt } from "../core/config.ts";
 import type { AnyStep } from "../core/steps.ts";
 import type { WebhookEvent } from "../core/webhooks.ts";
 import { pipelineData, type PipelineData, type StageNode } from "../builder/pipeline.ts";
@@ -46,14 +47,43 @@ const USAGE = "usage: step describe [--sentinels] | step run <step> | step map-t
 
 export function allSteps(data: PipelineData): AnyStep[] {
   const out: AnyStep[] = [];
-  const walk = (nodes: readonly StageNode[]) => {
-    for (const n of nodes) n.kind === "stage" ? out.push(...n.steps.map((s) => s.step)) : walk(n.nodes);
+  for (const { step } of stepsWithCases(data)) if (!out.includes(step)) out.push(step);
+  return out;
+}
+
+/** Every step with the `select` case conditions (`<ref>.<discriminator>=<value>`) it sits in. */
+export function stepsWithCases(data: PipelineData): { step: AnyStep; cases: string[] }[] {
+  const out: { step: AnyStep; cases: string[] }[] = [];
+  const walk = (nodes: readonly StageNode[], cases: string[]) => {
+    for (const n of nodes) {
+      if (n.kind === "stage") out.push(...n.steps.map((s) => ({ step: s.step, cases })));
+      else if (n.kind === "when") walk(n.nodes, cases);
+      else {
+        const union = isConfigRef(n.on) ? unionAt(n.on) : undefined;
+        for (const [value, inner] of Object.entries(n.cases))
+          walk(inner, union ? [...cases, `${configRefPath(n.on)}.${union.discriminator}=${value}`] : cases);
+      }
+    }
   };
-  walk(data.nodes);
-  for (const fh of data.failureHandlers) if (!out.includes(fh.step)) out.push(fh.step);
+  walk(data.nodes, []);
+  for (const fh of data.failureHandlers) out.push({ step: fh.step, cases: [] });
   return out;
 }
 
+/** The step `run <name>` executes: the only one so named, or the one in the cases the service selected (`OLVE_CASES`). */
+export function findStep(data: PipelineData, name: string, selected: readonly string[]): AnyStep | string {
+  const candidates = stepsWithCases(data).filter((c) => c.step.name === name);
+  const distinct = candidates.filter((c, i) => candidates.findIndex((d) => d.step === c.step) === i);
+  if (distinct.length === 0) return `unknown step '${name}'`;
+  if (distinct.length === 1) return distinct[0]!.step;
+  const chosen = distinct.filter((c) => c.cases.every((k) => selected.includes(k)));
+  if (chosen.length === 1) return chosen[0]!.step;
+  return `step '${name}' is in several select cases; ${ENV_CASES} must name the selected one (got ${JSON.stringify(selected)})`;
+}
+
+/** The select case conditions of the step being run (JSON array), set by the service for steps inside a select. */
+export const ENV_CASES = "OLVE_CASES";
+
 /** Installs SIGTERM/SIGINT handlers that abort the returned signal (PID 1 ignores signals without them). */
 export function cancellation(): { signal: AbortSignal; dispose(): void } {
   const ac = new AbortController();
@@ -136,8 +166,8 @@ async function describeMode(cfg: HarnessConfig, args: string[], io: HarnessIO):
 async function runMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
   if (!name) return io.stderr(USAGE), EXIT.usage;
   const data = pipelineData(cfg.pipeline);
-  const step = allSteps(data).find((s) => s.name === name);
-  if (!step) return io.stderr(`unknown step '${name}'`), EXIT.usage;
+  const step = findStep(data, name, selectedCases());
+  if (typeof step === "string") return io.stderr(step), EXIT.usage;
   const fn = await resolveStepFunction(step, cfg.handlers);
   if (typeof fn === "string") return io.stderr(fn), EXIT.configInvalid;
 
@@ -230,3 +260,12 @@ export async function runHarness(cfg: HarnessConfig, argv: readonly string[], io
 }
 
 export { formatIssues, formatLog };
+
+function selectedCases(): string[] {
+  try {
+    const v = JSON.parse(process.env[ENV_CASES] ?? "[]") as unknown;
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/harness/validate.ts

@@ -44,13 +44,31 @@ function entrySchema(e: unknown): z.ZodType {
   return e as z.ZodType;
 }
 
+/** Reserved input.json key holding the step's config entries (written by the service). */
+export const CONFIG_KEY = "$config";
+
+/** Parses `$config` with each declared entry's schema (defaults applied). Undeclared entries are ignored. */
+export function validateConfig(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
+  const given = isPlainObject(raw) ? raw[CONFIG_KEY] : undefined;
+  if (given !== undefined && !isPlainObject(given)) return { ok: false, issues: [`input.${CONFIG_KEY} must be an object keyed by config entry names`] };
+  const issues: string[] = [];
+  const out: Record<string, unknown> = {};
+  for (const e of step.config ?? []) {
+    const value = given?.[e.name];
+    const r = e.schema.safeParse(value);
+    if (!r.success) issues.push(...formatIssues(r.error, `config.${e.name}`).map((i) => (value === undefined ? `${i} (config entry '${e.name}' is not set)` : i)));
+    else if (r.data !== undefined) out[e.name] = r.data;
+  }
+  return issues.length ? { ok: false, issues } : { ok: true, value: out };
+}
+
 /** Validates input.json against the step's input entries. Unknown top-level keys are rejected; nested values are parsed (unknown nested keys stripped). */
 export function validateInput(step: AnyStep, raw: unknown): Validation<Record<string, unknown>> {
   if (!isPlainObject(raw)) return { ok: false, issues: ["input.json must be a JSON object keyed by the step's input names"] };
   const issues: string[] = [];
   const out: Record<string, unknown> = {};
   const declared = step.input as Record<string, unknown>;
-  for (const k of Object.keys(raw)) if (!Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
+  for (const k of Object.keys(raw)) if (k !== CONFIG_KEY && !Object.hasOwn(declared, k)) issues.push(`input.${k}: not an input of step '${step.name}'`);
   for (const [k, e] of Object.entries(declared)) {
     if (!Object.hasOwn(raw, k)) {
       if (isOptional(e)) continue;

package/src/index.ts

@@ -3,10 +3,11 @@
 export { z } from "zod";
 export { model, fileRef, optional, type Model, type AnyModel, type Infer, type InferInput, type Plain, type FileRef, type Optional } from "./core/models.ts";
 export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
+export { config, secretRef, type ConfigEntry, type AnyConfigEntry, type ConfigValues, type ConfigRef, type ConfigNode, type Configurable, type DiscriminatorOf, type VariantOf } from "./core/config.ts";
 export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
-export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
+export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type ConfigOf, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
 export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";
 export type { Ref, Mappable, MapperResult } from "./builder/refs.ts";
 export { pipeline, Pipeline, type PipelineDef, type InRefs, type InitialAvail, type WhenCond, type PushEvent, type StageEntry, type CheckStage, type MapperFn } from "./builder/pipeline.ts";
-export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type HelmDeployOverSshDef, httpHealthCheck, type HttpHealthCheckOptions, sshSession, shq, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";
+export { steps, Source, BuiltImage, PushedImage, HelmRelease, FailureContext, type RunValue, type ScriptDef, type GitHubSourceDef, type ImageBuildDef, type ImageBuildTarballDef, type ImageBuildPushDef, type RegistryAuth, type HelmDeployOverSshDef, helmTarget, deployTarget, type ComposeTargetValue, type HelmDeployInClusterDef, type HelmDeploySshTargetDef, type HelmTargetValue, type InClusterTargetValue, type SshTargetValue, registryTag, registryDigest, type RegistryAuthConfig, type RegistryAccess, npmDistTag, npmHasVersion, httpHealthCheck, type HttpHealthCheckOptions, sshSession, shq, type SshSession, serviceUrl, checkSpa } from "./library/index.ts";

package/src/library/compose-deploy.ts

@@ -0,0 +1,93 @@
+// steps.composeDeploy — ask a Docker Compose deployer to recreate a service with an image. The step is
+// thin on purpose: the deployer (pull, recreate, health, rollback) lives beside the compose project
+// and is fixed there, behind a versioned HTTP API, without editing pipelines.
+import type { Ctx } from "../ctx/types.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
+import type { Secret } from "../core/secrets.ts";
+import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { httpHealthCheck } from "./http-health.ts";
+import { HelmRelease, PushedImage } from "./models.ts";
+
+/** The step's own image: the work is one HTTP call from the harness. */
+export const COMPOSE_DEPLOY_IMAGE = "alpine:3.22";
+
+/** A resolved `kind: compose` target. */
+export interface ComposeTargetValue {
+  kind: "compose";
+  deployerUrl: string;
+  service: string;
+  token: { secret: string };
+  healthUrl?: string | undefined;
+}
+
+/** What the deployer answers to `POST /v1/deploy`. */
+export interface ComposeDeployResult {
+  status: "deployed" | "rolled-back" | "failed";
+  service: string;
+  image: string;
+  previousImage?: string;
+  message?: string;
+  log?: string[];
+}
+
+export interface ComposeDeployDef<N extends string, K extends string> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** A compose target, usually a `select` case's reference. */
+  target: Configurable<ComposeTargetValue>;
+  /** The secret the target's `token` names (declared by the step). */
+  token: Secret<K>;
+  timeoutSeconds?: number;
+}
+
+const input = { image: PushedImage };
+
+/**
+ * Deploys a registry image (by digest) to a compose service: `POST <deployerUrl>/v1/deploy
+ * { service, image: <repository>@<digest> }` with the target's bearer token. The deployer pulls the
+ * image, recreates the service, waits for its health and rolls back on failure; the step reports its
+ * answer, then (with the target's `healthUrl`) checks health itself. Output: a `HelmRelease` with the
+ * service as `release` and `compose` as `namespace`, so it can share a step name with the helm deploys.
+ */
+export function composeDeploy<const N extends string, const K extends string>(
+  def: ComposeDeployDef<N, K>,
+): Step<N, typeof input, typeof HelmRelease, K> & LibraryStep {
+  const configurable = { target: def.target };
+  return makeStep(
+    "composeDeploy",
+    { name: def.name, description: def.description, image: COMPOSE_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.token], timeoutSeconds: def.timeoutSeconds },
+    {
+      manifestConfig: () => ({ target: recordConfigRefs(def.target), token: def.token.name }),
+      async run({ image }: { image: { repository: string; digest: string } }, ctx: Ctx) {
+        const { target } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: ComposeTargetValue };
+        if (target?.kind !== "compose") throw new Error(`composeDeploy '${def.name}': the target is kind '${String(target?.kind)}', not 'compose'`);
+        if (target.token.secret !== def.token.name) throw new Error(`composeDeploy '${def.name}': the target's token names secret ${target.token.secret}, but the step declares ${def.token.name}`);
+        const token = (ctx.secrets as Record<string, string>)[def.token.name];
+        const ref = `${image.repository}@${image.digest}`;
+        const url = `${target.deployerUrl.replace(/\/+$/, "")}/v1/deploy`;
+        ctx.log("deploying", { service: target.service, image: ref, deployer: target.deployerUrl });
+        const res = await ctx.http.fetch(url, {
+          method: "POST",
+          headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          body: JSON.stringify({ service: target.service, image: ref }),
+        });
+        const text = await res.text();
+        let result: ComposeDeployResult | undefined;
+        try {
+          result = JSON.parse(text) as ComposeDeployResult;
+        } catch {
+          // reported below
+        }
+        for (const line of result?.log ?? []) ctx.log(`deployer: ${line}`);
+        if (!res.ok || result?.status !== "deployed")
+          throw new Error(`the deployer answered HTTP ${res.status}: ${result ? `${result.status}${result.message ? `: ${result.message}` : ""}` : text.slice(0, 300)}`);
+        if (target.healthUrl) await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+        ctx.log("deployed", { service: target.service, image: ref, previous: result.previousImage ?? "-" });
+        return { release: target.service, namespace: "compose", image: ref };
+      },
+    },
+    configurable,
+  ) as never;
+}

package/src/library/github-source.ts

@@ -7,6 +7,8 @@ import { join } from "node:path";
 import { z } from "zod";
 import type { Ctx } from "../ctx/types.ts";
 import type { Secret } from "../core/secrets.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
 import { extractTar } from "../util/tar.ts";
 import { Source } from "./models.ts";
@@ -23,11 +25,25 @@ export interface GitHubSourceDef<N extends string, T extends string> {
   description: string;
   /** Token sent to the GitHub API (needed for private repositories; raises the rate limit). */
   token?: Secret<T>;
+  /** GitHub API base (default `https://api.github.com`; GitHub Enterprise: `https://<host>/api/v3`). */
+  apiUrl?: Configurable<string | undefined>;
   timeoutSeconds?: number;
 }
 
+export const GITHUB_API_URL = "https://api.github.com";
+
+/** A declared secret's value, or "" when it is not set. */
+function optionalSecret(ctx: Pick<Ctx, "secrets">, name: string): string {
+  try {
+    return ((ctx.secrets as Record<string, string>)[name] ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
 /** Tarball URL of `repo` at `sha` (the API redirects to codeload.github.com). */
-export const gitHubTarballUrl = (repo: string, sha: string): string => `https://api.github.com/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
+export const gitHubTarballUrl = (repo: string, sha: string, apiUrl = GITHUB_API_URL): string =>
+  `${apiUrl.replace(/\/+$/, "")}/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
 
 /**
  * Downloads `repo` at `sha` from GitHub as a tarball and outputs it as a `Source` whose `tree` is the
@@ -41,11 +57,13 @@ export function gitHubSource<const N extends string, const T extends string = ne
     "gitHubSource",
     { name: def.name, description: def.description, image: GITHUB_SOURCE_IMAGE, input, output: Source, secrets: def.token ? [def.token] : [], timeoutSeconds: def.timeoutSeconds },
     {
-      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}) }),
+      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}), ...(def.apiUrl !== undefined ? { apiUrl: recordConfigRefs(def.apiUrl) } : {}) }),
       async run({ repo, sha }: { repo: string; sha: string }, ctx: Ctx) {
         const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
-        if (def.token) headers.authorization = `Bearer ${ctx.secrets[def.token.name]}`;
-        const url = gitHubTarballUrl(repo, sha);
+        const token = def.token ? optionalSecret(ctx, def.token.name) : "";
+        if (token) headers.authorization = `Bearer ${token}`;
+        else if (def.token) ctx.log(`${def.token.name} is not set: fetching anonymously (public repositories only)`);
+        const url = gitHubTarballUrl(repo, sha, resolveConfigRefs(def.apiUrl, ctx.config ?? {}) ?? GITHUB_API_URL);
         mkdirSync(ctx.tmpDir, { recursive: true });
         const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
         const archive = join(dir, "repo.tar.gz");
@@ -73,5 +91,6 @@ export function gitHubSource<const N extends string, const T extends string = ne
         return { repo, sha, tree };
       },
     },
+    { apiUrl: def.apiUrl },
   ) as never;
 }