Scheduled pipelines

triggers.schedule (inside cicd({ pipeline: { triggers } })) declares cron schedules in code, each in an optional local IANA timezone. GitHub Actions and Azure Pipelines only understand UTC cron, so Zuke compiles a { cron, tz } entry into the UTC cron(s) that fire at the intended local wall-clock time.

Concept

A daylight-saving zone uses two UTC offsets across the year, so the intended local time maps to two UTC crons (one per offset). Zuke registers both and generates a wall-clock guard so only the firing at the currently-correct offset proceeds. A fixed-offset zone (or plain UTC / an omitted tz) needs a single cron and no guard.

ScheduleEntry API

Each entry is a plain 5-field cron plus an optional IANA zone:

/** A scheduled trigger: a 5-field cron expression in an optional IANA timezone. */
export interface ScheduleEntry {
  cron: string;   // standard 5-field: minute hour day-of-month month day-of-week
  tz?: string;    // IANA zone (e.g. "Europe/Sofia"); omitted/"UTC" = already UTC, emitted verbatim
}
// on CiTriggers:  schedule?: ScheduleEntry[];
// lives at spec.pipeline.triggers.schedule inside cicd(spec)
export function cicd(spec: CiFileSpec): CiFile
export interface CiFileSpec {
  provider: CiProvider;            // "github" | "gitlab" | "azure" | "bitbucket"
  path?: string;
  pipeline?: CiPipeline;           // { name?, triggers?, permissions?, concurrency?, jobs? }
  fanOut?: boolean | FanOutOptions;
}
// helpers: utcCronsFor(entry): string[]; scheduleNeedsGuard(entry): boolean;
//          anyScheduleNeedsGuard(schedule): boolean; guardShell(schedule): string

The canonical example — weekday mornings and afternoons, Sofia local time:

ci = cicd({
  provider: "github",
  pipeline: {
    triggers: {
      push: ["main"],
      // Weekday mornings and afternoons, Sofia local time.
      schedule: [{ cron: "30 9,13,15 * * 1-4", tz: "Europe/Sofia" }],
    },
  },
});

Per-provider compilation

Cron grammar

Zuke supports a deliberate subset of cron syntax — five fields:

• minute (0–59), hour (0–23), day-of-month (1–31), month (1–12), day-of-week (0–7)
• each field: *, a single number, comma lists, ranges (a-b), or slash steps (*/n or a-b/n)
• day-of-week 0 and 7 both mean Sunday
• the timezone must have a whole-hour UTC offset

Errors

An unsupported schedule is reported before any file is generated, with a friendly message pointing at the fix — wrong field count, named fields/hashes/non-numeric values, bad steps, out-of-range values, an unknown timezone, a fractional-hour zone, or a day-crossing shift while a day field is constrained:

cicd: unsupported schedule — <reason>. Write the cron in UTC directly (drop the tz), or simplify it.

# Azure, DST-zone entry:
cicd: Azure Pipelines schedules are UTC-only and Zuke's daylight-saving guard is
GitHub-only. Use a fixed-offset timezone, or write the cron in UTC, for the azure provider.

Drift & determinism

tz omitted, "", or "UTC" emits the cron verbatim — single, no guard. Overlapping UTC crons across entries are collapsed via a Set. Because offsets are sampled from a pinned reference year, the output is deterministic:

zuke generate-ci --check   # fails on drift: "Run zuke generate-ci and commit the result."
zuke generate-ci          # running the build also auto-regenerates

zuke generate-ci --check verifies the on-disk file matches the rendered output and fails on drift; running the build also auto-regenerates the file. See Code-first CI/CD for the rest of the cicd() surface — providers, fan-out, and the portable step subset.