@zuke/gh

`@zuke/gh` — typed GitHub tooling for Zuke builds: the `gh` (GitHub CLI) task

Symbols

# CorrelateMode type

type CorrelateMode = marker | created-window

How githubWorkflow correlates the run it dispatched: - "marker" — match the zuke:<runId>:<target> marker echoed into the run's run-name: (exact, but the target workflow must opt in). - "created-window" — claim the workflow_dispatch run on the dispatch ref created just after dispatch; best-effort, for workflows that can't echo the marker (fails loudly if two candidates are in the window).

# GhSettings class

class GhSettings extends SubcommandSettings

Settings for a gh invocation.

Member	Signature	Doc
`repo`	`repo(slug: string): this`	Target repository as `OWNER/REPO` (`-R`/`--repo`).

# GhTasks const

const GhTasks: GhTasksApi

Typed task functions for the gh GitHub CLI.

# GhTasksApi interface

interface GhTasksApi

The shape of GhTasks.

Member	Signature	Doc
`run`	`run(configure?: Configure<GhSettings>): Promise<CommandOutput>`	Run a `gh` command.

# githubWorkflow function

function githubWorkflow(configure: unknown): WaitTrigger

A "@zuke/core".WaitTrigger that dispatches a GitHub Actions workflow, suspends the run until it finishes, and records its per-job conclusions to the awaiting target's state (read them with readWorkflowResult). See the module docs for the run-name correlation requirement and auth.

githubWorkflow((g) => g.repo("acme/app").workflow("e2e.yml").ref("main"))

# GithubWorkflowSettings class

class GithubWorkflowSettings

Configuration for githubWorkflow, set through a settings lambda. Every setter returns this so calls chain; repo and workflow are required.

Member	Signature	Doc
`repo`	`repo(slug: string): this`	Set the `OWNER/REPO` the workflow lives in.
`workflow`	`workflow(idOrFile: string): this`	Set the workflow file name (e.g. `e2e.yml`) or numeric id.
`ref`	`ref(ref: string): this`	Set the git ref to dispatch against (default `main`).
`input`	`input(name: string, value: string): this`	Add one `workflow_dispatch` input.
`inputs`	`inputs(map: Record<string, string>): this`	Merge a map of `workflow_dispatch` inputs.
`markerInput`	`markerInput(name: string): this`	Change the input name the correlation marker is dispatched as.
`correlate`	`correlate(mode: CorrelateMode): this`	How the dispatched run is correlated: `"marker"` (default) matches the marker echoed into the run's `run-name:`; `"created-window"` claims the `workflow_dispatch` run on the dispatch ref created just after dispatch — a best-effort fallback for a workflow that cannot echo the marker.
`discoveryTimeout`	`discoveryTimeout(duration: string): this`	How long after dispatch to keep looking for the run before failing fast with guidance (a duration string; default one minute). Bounds the "workflow never echoed the marker" failure so it surfaces in ~a minute instead of eating the whole `.timeout()`.
`pollEvery`	`pollEvery(duration: string): this`	Set how often `zuke resume --check` should re-poll (a duration string).
`repo_?`	`repo_?: string`	The `OWNER/REPO` slug the workflow lives in.
`workflow_?`	`workflow_?: string`	The workflow file name (e.g. `e2e.yml`) or its numeric id.
`ref_`	`ref_: string`	The git ref to dispatch against (default `main`).
`inputs_`	`inputs_: Record<string, string>`	Extra `workflow_dispatch` inputs.
`markerInput_`	`markerInput_: string`	The input name the marker is passed as (default `zuke_marker`).
`correlateMode_`	`correlateMode_: CorrelateMode`	How the dispatched run is correlated (default `"marker"`); set by `correlate`.
`discoveryTimeoutMs_?`	`discoveryTimeoutMs_?: number`	How long to wait for the run to appear before failing fast (ms); set by `discoveryTimeout`.
`pollIntervalMs_?`	`pollIntervalMs_?: number`	Poll interval hint (ms) for `zuke resume --check`.

# readWorkflowResult function

function readWorkflowResult(state: TargetStateHandle): WorkflowResult | undefined

Read the WorkflowResult a completed githubWorkflow wait wrote to a target's state, or undefined if the wait has not completed (or this is not a github-workflow gate). Call it from a dependent target's body with the gate's handle: readWorkflowResult(ctx.stateOf("<gate-target>")).

# WorkflowCorrelationError class

class WorkflowCorrelationError extends Error

A githubWorkflow correlation failure the wait must not swallow as a transient blip: the dispatched run could not be identified (it never echoed the marker within the discovery window, or created-window correlation found more than one candidate). Thrown from the trigger so the waiting target fails with guidance instead of eating the whole .timeout().

Member	Signature	Doc
`name`	`name: string`	The error name, `"WorkflowCorrelationError"`.

# WorkflowJob interface

interface WorkflowJob

One job's outcome within a completed workflow run.

Member	Signature	Doc
`name`	`name: string`	The job's name.
`conclusion`	`conclusion: string`	Its conclusion (`success`, `failure`, `cancelled`, `skipped`, …).
`url`	`url: string`	A link to the job on GitHub.

# WorkflowResult interface

interface WorkflowResult

The payload a completed githubWorkflow wait writes to the awaiting target's state; read it in a dependent body with readWorkflowResult.

Member	Signature	Doc
`passed`	`passed: boolean`	True when the run's overall conclusion was `success`.
`conclusion`	`conclusion: string`	The run's overall conclusion.
`runId`	`runId: number`	The dispatched run's numeric id.
`url`	`url: string`	A link to the run on GitHub.
`jobs`	`jobs: WorkflowJob[]`	Each job's conclusion, so a build can branch on which suite failed.