@zuke/gh

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

Symbols

assertRefName

function

function assertRefName(name: string, what: string): void

Reject a branch or tag name that git itself would.

Not cosmetic. These names are interpolated into request paths, and URL normalisation resolves .. before the request is sent — so ../../../user/repos as a branch turns /repos/o/n/git/ref/heads/<branch> into /repos/o/n/user/repos, sending a write-scoped token somewhere the caller never named. Validating here rather than trusting every caller is the difference between an API that is safe to hand a string and one that is safe only when used carefully.

The rules are git's own (see git check-ref-format), minus those that only matter for multi-level refs.

CACHE_LIST_FIELDS

const

const CACHE_LIST_FIELDS: unknown

The --json fields readCaches asks for; gh requires the list by name, so the reader pins the set GhCacheEntry describes.

commitFiles

function

async function commitFiles(configure?: unknown): Promise<GhCommitResult>

Perform the configured commit.

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

ensureRelease

function

async function ensureRelease(configure?: Configure<GhReleaseEnsureSettings>): Promise<GhReleaseEnsureResult>

Perform the configured ensure-release call.

findPullRequest

function

async function findPullRequest(configure?: unknown): Promise<GhPullRequestResult | undefined>

Look for an open pull request without opening one.

GhApiError

class

class GhApiError extends Error

A GitHub REST call that did not succeed, carrying the status.

The status is the point. Callers recover from specific failures — a missing ref, a pull request that already exists — and doing that on a bare catch would swallow an expired token or a missing permission and retry it as though it were the expected case.

Member	Signature	Doc
`name`	`name: string`	The error name.
`status`	`status: number`	The HTTP status of the failing response.

GhApiSettings

class

class GhApiSettings extends ToolSettings

Settings for GhTasks.api, mirroring the real gh api flags: --method, --field, --raw-field, --header, --jq, and --silent.

Member	Signature	Doc
`method`	`method(verb: string): this`	The HTTP method (`--method`, e.g. `"PUT"`; `gh` defaults to GET).
`field`	`field(key: string, value: string \| number \| boolean): this`	Add a typed body parameter (`--field key=value`). Repeatable.
`rawField`	`rawField(key: string, value: string): this`	Add a string body parameter (`--raw-field key=value`). Repeatable.
`header`	`header(name: string, value: string): this`	Add a request header (`--header key:value`). Repeatable.
`jq`	`jq(expression: string): this`	Filter the response through a jq expression (`--jq`).
`silent`	`silent(): this`	Do not print the response body (`--silent`).

GhAppTokenApi

interface

interface GhAppTokenApi

The shape of the app-token task, mixed into GhTasks.

Member	Signature	Doc
`appToken`	`appToken(configure?: Configure<GhAppTokenSettings>): Promise<GhAppTokenResult>`	Mint a GitHub App installation token, scoped to the repositories and permissions the settings request. The returned token is registered with the Actions log masker, so it is safe to pass onward through `env`.

GhAppTokenResult

interface

interface GhAppTokenResult

A minted installation token and when it stops working.

Member	Signature	Doc
`token`	`token: string`	The installation token, usable as a bearer token or a git password.
`expiresAt`	`expiresAt: string`	ISO-8601 expiry — one hour out, as GitHub issues it.
`installationId`	`installationId: number`	The installation the token was minted for.

GhAppTokenSettings

class

class GhAppTokenSettings

Settings for GhAppTokenApi.appToken.

Member	Signature	Doc
`appId`	`appId(id: string \| number): this`	The GitHub App's id (the `App ID` on its settings page).
`privateKey`	`privateKey(pem: string): this`	The app's private key, as the PEM's contents — GitHub issues PKCS#1 (`BEGIN RSA PRIVATE KEY`); PKCS#8 is accepted too.
`owner`	`owner(login: string): this`	The user or organisation the app is installed on.
`repositories`	`repositories(...names: string[]): this`	Scope the token to these repositories (names only, without the owner). Omit to cover every repository the installation can reach — prefer naming them, so a leaked token is narrow.
`permission`	`permission(name: string, level: GhPermissionLevel): this`	Request one permission, e.g. `.permission("contents", "write")`. Repeatable. Narrowing to what the target needs beats inheriting the app's full set; requesting more than the installation grants is an error from GitHub. The API names multi-word permissions with underscores (`pull_requests`), so a hyphen is normalised to one. That spelling is the trap here: `create-github-app-token` takes its inputs as `permission-pull-requests`, and passing that form straight through is rejected as a permission the installation does not grant — which reads as a misconfigured app rather than a misspelled key.
`baseUrl`	`baseUrl(url: string): this`	Use a different REST base (GitHub Enterprise Server).
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`now`	`now(seconds: unknown): this`	Override the clock, in seconds since the epoch (a test seam).
`jwt_`	`jwt_(): Promise<string>`	Sign the app JWT this settings object describes.
`installationPath_`	`installationPath_(): string`	The path that resolves this app's installation id.
`tokenRequest_`	`tokenRequest_(): Record<string, unknown>`	The `access_tokens` request body — only the fields that were narrowed.
`appId_?`	`appId_?: string`	The app's numeric id. Set by `appId`.
`privateKey_?`	`privateKey_?: string`	The app's PEM private key. Set by `privateKey`.
`owner_?`	`owner_?: string`	The account the app is installed on. Set by `owner`.
`repositories_`	`repositories_: string[]`	Repositories to scope the token to. Set by `repositories`.
`permissions_`	`permissions_: Record<string, GhPermissionLevel>`	Requested permissions. Set by `permission`.
`baseUrl_`	`baseUrl_: string`	REST base URL. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.
`now_`	`now_: unknown`	Seconds since the epoch, for the JWT's claims. Set by `now`.

GhBodySettings

class

class GhBodySettings extends GhCommandSettings

Base for the commands that take message text: pr create, pr comment, pr edit, issue create, issue comment.

gh spells it --body for the text and --body-file for a file, with - meaning standard input — the same pair on every one of them.

Member	Signature	Doc
`body`	`body(text: string): this`	The message text (`--body`).
`bodyFile`	`bodyFile(path: PathLike): this`	Read the message from a file (`--body-file`); `-` reads standard input.

GhCacheApi

interface

interface GhCacheApi

The gh cache members of "./gh.ts".GhTasks.

Member	Signature	Doc
`cacheList`	`cacheList(configure?: Configure<GhCacheListSettings>): Promise<CommandOutput>`	List the Actions caches: `gh cache list`.
`cacheListEntries`	`cacheListEntries(configure?: Configure<GhCacheListSettings>): Promise<GhCacheEntry[]>`	The caches as parsed `GhCacheEntry` values — what a build reads to decide which ones to reclaim.
`cacheDelete`	`cacheDelete(configure?: Configure<GhCacheDeleteSettings>): Promise<CommandOutput>`	Reclaim caches: `gh cache delete`.

GhCacheDeleteSettings

class

class GhCacheDeleteSettings extends GhCommandSettings

Settings for gh cache delete.

Member	Signature	Doc
`selector`	`selector(idOrKey: string \| number): this`	The cache to delete, by its id or its key.
`all`	`all(): this`	Delete every cache (`--all`), narrowed by `ref` when one is set.
`ref`	`ref(name: string): this`	Restrict the deletion to one ref (`--ref`).
`succeedOnNoCaches`	`succeedOnNoCaches(): this`	Exit zero when there was nothing to delete (`--succeed-on-no-caches`).

GhCacheEntry

interface

interface GhCacheEntry

One cache of "./gh.ts".GhTasks.cacheListEntries.

Member	Signature	Doc
`id?`	`id?: number`	The cache's numeric id — what `GhCacheDeleteSettings` takes.
`key?`	`key?: string`	Its key, as the workflow that saved it chose.
`ref?`	`ref?: string`	The ref it belongs to.
`sizeInBytes?`	`sizeInBytes?: number`	How much space it occupies, in bytes.
`createdAt?`	`createdAt?: string`	When it was created, ISO 8601.
`lastAccessedAt?`	`lastAccessedAt?: string`	When it was last read, ISO 8601 — what eviction goes by.

GhCacheListSettings

class

class GhCacheListSettings extends GhReadSettings

Settings for gh cache list.

Member	Signature	Doc
`key`	`key(prefix: string): this`	Only caches whose key starts with this (`--key`).
`ref`	`ref(name: string): this`	Only caches for this ref (`--ref`), e.g. `refs/heads/master`.
`sort`	`sort(field: GhCacheSort): this`	What to order by (`--sort`); gh's default is `last_accessed_at`.
`order`	`order(direction: asc \| desc): this`	The direction (`--order`): `asc` or `desc`.
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.

GhCacheSort

type

type GhCacheSort = created_at | last_accessed_at | size_in_bytes

What gh cache list --sort orders the caches by.

GhCheckConclusion

type

type GhCheckConclusion = success | failure | neutral | cancelled | skipped | timed_out | action_required

A check run's conclusion, as GitHub spells them.

"stale" is deliberately absent: GitHub sets it itself and rejects it from a caller.

GhCheckRunApi

interface

interface GhCheckRunApi

The check-run operation GhTasks exposes.

Member	Signature	Doc
`checkRun`	`checkRun(configure?: unknown): Promise<GhCheckRunResult>`	Post a completed check run for `.headSha(...)` named `.name(...)`, updating the one already on that commit if there is one. The lookup and the write are two calls, so this is an upsert by convergence, not an atomic one: two callers racing on a commit that has no check run yet can both find nothing and both create one. What it removes is the serial duplicate — the retry, the re-drive, the supervisor finishing a dead process's work — which is the case that actually happens.

GhCheckRunResult

interface

interface GhCheckRunResult

The check run a GhCheckRunApi.checkRun call left on the commit.

Member	Signature	Doc
`id`	`id: number`	Its numeric id.
`url`	`url: string`	Its web URL.
`created`	`created: boolean`	Whether this call created it, as opposed to updating one already there. Worth reporting rather than hiding: a caller that expected to create and updated instead has learned that something else posted first, which is the difference between a first attempt and a re-drive.

GhCheckRunSettings

class

class GhCheckRunSettings

Settings for posting a completed check run.

owner/repo and the token fall back to the Actions environment, so a job that already has them names only what it is reporting.

Member	Signature	Doc
`name`	`name(value: string): this`	The check run's name — what appears in the PR's checks list, and what a branch protection rule names as a required status context.
`headSha`	`headSha(sha: string): this`	The full SHA of the commit being reported on. Pin this at the start of the work, not when the result is posted. A caller that resolves the head of a pull request at post time reports on whatever has been pushed since — which, for a required context, is a green check on a commit nothing ever tested.
`conclusion`	`conclusion(value: GhCheckConclusion): this`	The conclusion to report.
`title`	`title(text: string): this`	The output panel's title. Defaults to the check run's name.
`summary`	`summary(markdown: string): this`	The output panel's body, as markdown.
`externalId`	`externalId(id: string): this`	A correlation id of the caller's own, stored on the check run. Also what this operation matches on when deciding whether a check run is "the same one": with an external id set, two callers writing the same name on the same commit for different reasons stay distinct, and a re-drive of one of them updates its own check run rather than the other's.
`detailsUrl`	`detailsUrl(url: string): this`	Where the check run's "Details" link points.
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`name_?`	`name_?: string`	The check run's name — half of its identity. Set by `name`.
`headSha_?`	`headSha_?: string`	The commit it reports on. Set by `headSha`.
`conclusion_?`	`conclusion_?: GhCheckConclusion`	The conclusion to report. Set by `conclusion`.
`title_?`	`title_?: string`	The output panel's title. Set by `title`.
`summary_?`	`summary_?: string`	The output panel's markdown body. Set by `summary`.
`externalId_?`	`externalId_?: string`	The caller's own correlation id. Set by `externalId`.
`detailsUrl_?`	`detailsUrl_?: string`	Where the check run's "Details" link points. Set by `detailsUrl`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhCloseReason

type

type GhCloseReason = completed | not planned | duplicate

Why an issue is being closed (--reason).

GhCommandSettings

class

class GhCommandSettings extends GhSettings

Base for a typed gh subcommand: it contributes the command path (the group, the verb, and any operand) and its own flags, and inherits everything else from "./settings.ts".GhSettings.

GhCommitApi

interface

interface GhCommitApi

The commit and tag operations GhTasks exposes.

Member	Signature	Doc
`commit`	`commit(configure?: unknown): Promise<GhCommitResult>`	Commit files through the API, with no git credential on disk. Commits onto `.branch(...)`, or creates it from `.from(...)` when that is set. The ref update is not forced, so a commit landing between reading the head and writing it is rejected rather than silently overwritten — unless `.replace()` is set, which resets an existing branch onto its base and discards whatever was on it.
`tag`	`tag(configure?: unknown): Promise<void>`	Point an annotated tag at a commit, creating or moving its ref.

GhCommitResult

interface

interface GhCommitResult

The commit a GhTasksApi.commit call created.

Member	Signature	Doc
`sha`	`sha: string`	The new commit's SHA.
`branch`	`branch: string`	The branch it landed on.

GhCommitSettings

class

class GhCommitSettings

Settings for committing files through the API.

owner/repo and the token fall back to the Actions environment, so a job that already has them needs to name only what it is committing.

Member	Signature	Doc
`file`	`file(path: string, content: string): this`	Add a file to the commit, replacing any earlier one at the same path.
`branch`	`branch(name: string): this`	The branch to commit onto. It must exist unless `from` is set.
`from`	`from(base: string): this`	Create `branch` from this one rather than committing onto an existing branch. Creating a ref and moving one are different calls, and which is wanted is the caller's to say rather than something to infer.
`replace`	`replace(): this`	Reset `branch` onto `from` when it already exists, rather than failing because it does. For a branch only one automated caller ever writes, and whose contents are regenerated in full each time. Without this, a job that creates the branch and then fails before opening its pull request can never retry: the second run is refused because the ref it wants to create is already there, and the work is stuck until someone deletes the branch by hand. Deliberately not the default. Discarding commits on a branch that already exists is exactly what should not happen to a branch someone is working on, so it stays something the caller asks for.
`message`	`message(text: string): this`	The commit message.
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`files_`	`files_: Map<string, string>`	The files to write, by path.
`branch_?`	`branch_?: string`	The branch to commit onto. Set by `branch`.
`from_?`	`from_?: string`	The branch to create from, when creating one. Set by `from`.
`replace_`	`replace_: boolean`	Whether an existing `branch` is reset. Set by `replace`.
`message_?`	`message_?: string`	The commit message. Set by `message`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhIssueApi

interface

interface GhIssueApi

The gh issue members of "./gh.ts".GhTasks.

Member	Signature	Doc
`issueCreate`	`issueCreate(configure?: Configure<GhIssueCreateSettings>): Promise<CommandOutput>`	Open an issue: `gh issue create`.
`issueList`	`issueList(configure?: Configure<GhIssueListSettings>): Promise<CommandOutput>`	List issues: `gh issue list`.
`issueListEntries`	`issueListEntries(configure?: Configure<GhIssueListSettings>): Promise<GhIssueEntry[]>`	The issues as parsed `GhIssueEntry` values. The `--json` field set is pinned, since gh requires one by name.
`issueView`	`issueView(configure?: Configure<GhIssueViewSettings>): Promise<CommandOutput>`	Show an issue: `gh issue view`.
`issueComment`	`issueComment(configure?: Configure<GhIssueCommentSettings>): Promise<CommandOutput>`	Comment on an issue: `gh issue comment`.
`issueClose`	`issueClose(configure?: Configure<GhIssueCloseSettings>): Promise<CommandOutput>`	Close an issue: `gh issue close`.

GhIssueCloseSettings

class

class GhIssueCloseSettings extends GhCommandSettings

Settings for gh issue close.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The issue — its number or URL (required).
`comment`	`comment(text: string): this`	Leave a closing comment (`--comment`).
`reason`	`reason(value: GhCloseReason): this`	Why it is closed (`--reason`).
`duplicateOf`	`duplicateOf(numberOrUrl: string \| number): this`	Which issue it duplicates (`--duplicate-of`), by number or URL.

GhIssueCommentSettings

class

class GhIssueCommentSettings extends GhBodySettings

Settings for gh issue comment.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The issue — its number or URL (required).
`editLast`	`editLast(): this`	Edit your most recent comment instead of adding one (`--edit-last`).
`createIfNone`	`createIfNone(): this`	With `editLast`, post a new comment when there is none (`--create-if-none`).
`deleteLast`	`deleteLast(): this`	Delete your most recent comment (`--delete-last`).
`yes`	`yes(): this`	Skip the confirmation a delete otherwise prompts for (`--yes`).

GhIssueCreateSettings

class

class GhIssueCreateSettings extends GhBodySettings

Settings for gh issue create.

Member	Signature	Doc
`title`	`title(text: string): this`	The issue's title (`--title`).
`assignee`	`assignee(...logins: string[]): this`	Assign someone by login (`--assignee`), `@me` for yourself; repeatable.
`label`	`label(...names: string[]): this`	Add a label by name (`--label`); repeatable.
`project`	`project(...titles: string[]): this`	Add to a project by title (`--project`); repeatable.
`milestone`	`milestone(name: string): this`	Add to a milestone by name (`--milestone`).
`type`	`type(name: string): this`	Set the issue type by name (`--type`).
`parent`	`parent(numberOrUrl: string \| number): this`	File it as a sub-issue of this number or URL (`--parent`).
`templateName`	`templateName(name: string): this`	The issue template to start the body from (`--template`).

GhIssueEntry

interface

interface GhIssueEntry

One issue of "./gh.ts".GhTasks.issueListEntries.

Member	Signature	Doc
`number?`	`number?: number`	The issue's number.
`title?`	`title?: string`	Its title.
`state?`	`state?: string`	Its state, as gh reports it: `OPEN` or `CLOSED`.
`url?`	`url?: string`	Its web URL.
`author?`	`author?: string`	The login of whoever opened it.

GhIssueListSettings

class

class GhIssueListSettings extends GhWebReadSettings

Settings for gh issue list.

Member	Signature	Doc
`state`	`state(value: open \| closed \| all): this`	Filter by state (`--state`): `open`, `closed`, or `all`.
`author`	`author(login: string): this`	Filter by author (`--author`).
`app`	`app(name: string): this`	Filter by the GitHub App that opened it (`--app`).
`assignee`	`assignee(login: string): this`	Filter by assignee (`--assignee`).
`mention`	`mention(login: string): this`	Filter by who is mentioned (`--mention`).
`milestone`	`milestone(nameOrNumber: string): this`	Filter by milestone number or title (`--milestone`).
`type`	`type(name: string): this`	Filter by issue type (`--type`).
`label`	`label(...names: string[]): this`	Filter by label (`--label`); repeatable.
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.
`search`	`search(query: string): this`	Filter with a search query (`--search`).

GhIssueViewSettings

class

class GhIssueViewSettings extends GhWebReadSettings

Settings for gh issue view.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The issue — its number or URL (required).
`comments`	`comments(): this`	Include the comments (`--comments`).

GhLabelApi

interface

interface GhLabelApi

The gh label members of "./gh.ts".GhTasks.

Member	Signature	Doc
`labelList`	`labelList(configure?: Configure<GhLabelListSettings>): Promise<CommandOutput>`	List labels: `gh label list`.
`labelListEntries`	`labelListEntries(configure?: Configure<GhLabelListSettings>): Promise<GhLabelEntry[]>`	The labels as parsed `GhLabelEntry` values. The `--json` field set is pinned, since gh requires one by name.
`labelCreate`	`labelCreate(configure?: Configure<GhLabelCreateSettings>): Promise<CommandOutput>`	Add a label: `gh label create`.
`labelEdit`	`labelEdit(configure?: Configure<GhLabelEditSettings>): Promise<CommandOutput>`	Change a label: `gh label edit`.
`labelDelete`	`labelDelete(configure?: Configure<GhLabelDeleteSettings>): Promise<CommandOutput>`	Remove a label: `gh label delete`.
`labelClone`	`labelClone(configure?: Configure<GhLabelCloneSettings>): Promise<CommandOutput>`	Copy another repository's labels: `gh label clone`.

GhLabelCloneSettings

class

class GhLabelCloneSettings extends GhCommandSettings

Settings for gh label clone.

Member	Signature	Doc
`source`	`source(slug: string): this`	The repository to copy the labels from, as `owner/name` (required).
`force`	`force(): this`	Overwrite labels of the same name in the destination (`--force`).

GhLabelCreateSettings

class

class GhLabelCreateSettings extends GhCommandSettings

Settings for gh label create.

Member	Signature	Doc
`name`	`name(value: string): this`	The label's name (required).
`color`	`color(hex: string): this`	Its colour (`--color`), as a hex triplet; gh accepts it with or without `#`.
`description`	`description(text: string): this`	Its description (`--description`).
`force`	`force(): this`	Update the label when it already exists rather than failing (`--force`).

GhLabelDeleteSettings

class

class GhLabelDeleteSettings extends GhCommandSettings

Settings for gh label delete.

Member	Signature	Doc
`name`	`name(value: string): this`	The label to delete (required).
`yes`	`yes(): this`	Skip the confirmation a delete otherwise prompts for (`--yes`).

GhLabelEditSettings

class

class GhLabelEditSettings extends GhCommandSettings

Settings for gh label edit.

Member	Signature	Doc
`name`	`name(value: string): this`	The label to edit, by its current name (required).
`newName`	`newName(value: string): this`	Rename it (`--name`).
`color`	`color(hex: string): this`	Set its colour (`--color`).
`description`	`description(text: string): this`	Set its description (`--description`).

GhLabelEntry

interface

interface GhLabelEntry

One label of "./gh.ts".GhTasks.labelListEntries.

Member	Signature	Doc
`name?`	`name?: string`	The label's name.
`color?`	`color?: string`	Its colour, as a hex triplet without the `#`.
`description?`	`description?: string`	Its description.

GhLabelListSettings

class

class GhLabelListSettings extends GhWebReadSettings

Settings for gh label list.

Member	Signature	Doc
`search`	`search(query: string): this`	Search names and descriptions (`--search`).
`sort`	`sort(field: GhLabelSort): this`	What to order by (`--sort`); gh's default is `created`.
`order`	`order(direction: asc \| desc): this`	The direction (`--order`): `asc` or `desc`.
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.

GhLabelSort

type

type GhLabelSort = created | name

What gh label list --sort orders the labels by.

GhMergeMethod

type

type GhMergeMethod = merge | squash | rebase

How gh pr merge combines the commits.

GhPermissionLevel

type

type GhPermissionLevel = read | write | admin

A permission level an installation token can be narrowed to.

GhPrApi

interface

interface GhPrApi

The gh pr members of "./gh.ts".GhTasks.

Member	Signature	Doc
`prCreate`	`prCreate(configure?: Configure<GhPrCreateSettings>): Promise<CommandOutput>`	Open a pull request: `gh pr create`. Needs the `gh` binary and its auth; `"./pull_request.ts".GhPullRequestApi.pullRequest` is the REST path, which needs a token instead.
`prList`	`prList(configure?: Configure<GhPrListSettings>): Promise<CommandOutput>`	List pull requests: `gh pr list`.
`prListEntries`	`prListEntries(configure?: Configure<GhPrListSettings>): Promise<GhPullRequestEntry[]>`	The pull requests as parsed `GhPullRequestEntry` values. The `--json` field set is pinned, since gh requires one by name.
`prView`	`prView(configure?: Configure<GhPrViewSettings>): Promise<CommandOutput>`	Show a pull request: `gh pr view`.
`prChecks`	`prChecks(configure?: Configure<GhPrChecksSettings>): Promise<CommandOutput>`	Report a pull request's checks: `gh pr checks`.
`prMerge`	`prMerge(configure?: Configure<GhPrMergeSettings>): Promise<CommandOutput>`	Merge a pull request: `gh pr merge`.
`prComment`	`prComment(configure?: Configure<GhPrCommentSettings>): Promise<CommandOutput>`	Comment on a pull request: `gh pr comment`.
`prEdit`	`prEdit(configure?: Configure<GhPrEditSettings>): Promise<CommandOutput>`	Change a pull request's metadata: `gh pr edit`.
`prClose`	`prClose(configure?: Configure<GhPrCloseSettings>): Promise<CommandOutput>`	Close a pull request: `gh pr close`.

GhPrChecksSettings

class

class GhPrChecksSettings extends GhPrReadSettings

Settings for gh pr checks.

Member	Signature	Doc
`watch`	`watch(): this`	Keep watching until the checks finish (`--watch`). A target that watches blocks until CI is done, so pair it with `.killAfter(...)` unless the wait is the point.
`failFast`	`failFast(): this`	Stop watching at the first failure (`--fail-fast`).
`required`	`required(): this`	Only the checks marked required (`--required`).
`interval`	`interval(seconds: number): this`	How often to refresh while watching (`--interval`), in seconds.

GhPrCloseSettings

class

class GhPrCloseSettings extends GhCommandSettings

Settings for gh pr close.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The pull request — number, URL, or branch; defaults to the current branch's.
`comment`	`comment(text: string): this`	Leave a closing comment (`--comment`).
`deleteBranch`	`deleteBranch(): this`	Delete the branch afterwards (`--delete-branch`).

GhPrCommentSettings

class

class GhPrCommentSettings extends GhPrTargetSettings

Settings for gh pr comment.

Member	Signature	Doc
`editLast`	`editLast(): this`	Edit your most recent comment instead of adding one (`--edit-last`).
`createIfNone`	`createIfNone(): this`	With `editLast`, post a new comment when there is none (`--create-if-none`).
`deleteLast`	`deleteLast(): this`	Delete your most recent comment (`--delete-last`).
`yes`	`yes(): this`	Skip the confirmation a delete otherwise prompts for (`--yes`).

GhPrCreateSettings

class

class GhPrCreateSettings extends GhBodySettings

Settings for gh pr create.

Member	Signature	Doc
`title`	`title(text: string): this`	The pull request's title (`--title`).
`base`	`base(branch: string): this`	The branch to merge into (`--base`).
`head`	`head(branch: string): this`	The branch holding the commits (`--head`).
`assignee`	`assignee(...logins: string[]): this`	Assign someone by login (`--assignee`), `@me` for yourself; repeatable.
`label`	`label(...names: string[]): this`	Add a label by name (`--label`); repeatable.
`reviewer`	`reviewer(...handles: string[]): this`	Request a review from a person or team (`--reviewer`); repeatable.
`milestone`	`milestone(name: string): this`	Add to a milestone by name (`--milestone`).
`project`	`project(...titles: string[]): this`	Add to a project by title (`--project`); repeatable.
`draft`	`draft(): this`	Open it as a draft (`--draft`).
`fill`	`fill(): this`	Take the title and body from the commits (`--fill`).
`fillFirst`	`fillFirst(): this`	Take them from the first commit only (`--fill-first`).
`fillVerbose`	`fillVerbose(): this`	Take the body from every commit's message (`--fill-verbose`).
`dryRun`	`dryRun(): this`	Print what would be created without creating it (`--dry-run`).
`noMaintainerEdit`	`noMaintainerEdit(): this`	Refuse maintainer edits to the branch (`--no-maintainer-edit`).
`templateFile`	`templateFile(path: string): this`	A template file to seed the body from (`--template`).

GhPrEditSettings

class

class GhPrEditSettings extends GhPrTargetSettings

Settings for gh pr edit.

Member	Signature	Doc
`title`	`title(text: string): this`	Set the title (`--title`).
`base`	`base(branch: string): this`	Change the base branch (`--base`).
`addLabel`	`addLabel(...names: string[]): this`	Add a label (`--add-label`); repeatable.
`removeLabel`	`removeLabel(...names: string[]): this`	Remove a label (`--remove-label`); repeatable.
`addAssignee`	`addAssignee(...logins: string[]): this`	Add an assignee (`--add-assignee`); repeatable.
`removeAssignee`	`removeAssignee(...logins: string[]): this`	Remove an assignee (`--remove-assignee`); repeatable.
`addReviewer`	`addReviewer(...handles: string[]): this`	Request a review (`--add-reviewer`); repeatable.
`removeReviewer`	`removeReviewer(...handles: string[]): this`	Drop a review request (`--remove-reviewer`); repeatable.
`addProject`	`addProject(...titles: string[]): this`	Add to a project by title (`--add-project`); repeatable.
`removeProject`	`removeProject(...titles: string[]): this`	Take it off a project by title (`--remove-project`); repeatable.
`milestone`	`milestone(name: string): this`	Set the milestone (`--milestone`).
`removeMilestone`	`removeMilestone(): this`	Clear the milestone (`--remove-milestone`).

GhPrListSettings

class

class GhPrListSettings extends GhWebReadSettings

Settings for gh pr list.

Member	Signature	Doc
`state`	`state(value: open \| closed \| merged \| all): this`	Filter by state (`--state`): `open`, `closed`, `merged`, or `all`.
`base`	`base(branch: string): this`	Filter by base branch (`--base`).
`head`	`head(branch: string): this`	Filter by head branch (`--head`).
`author`	`author(login: string): this`	Filter by author (`--author`).
`app`	`app(name: string): this`	Filter by the GitHub App that opened it (`--app`).
`assignee`	`assignee(login: string): this`	Filter by assignee (`--assignee`).
`label`	`label(...names: string[]): this`	Filter by label (`--label`); repeatable.
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.
`search`	`search(query: string): this`	Filter with a search query (`--search`).
`draft`	`draft(): this`	Only draft pull requests (`--draft`).

GhPrMergeSettings

class

class GhPrMergeSettings extends GhPrTargetSettings

Settings for gh pr merge.

Member	Signature	Doc
`merge`	`merge(): this`	Merge with a merge commit (`--merge`).
`squash`	`squash(): this`	Squash the commits into one (`--squash`).
`rebase`	`rebase(): this`	Rebase the commits onto the base (`--rebase`).
`auto`	`auto(): this`	Merge once the requirements are met (`--auto`).
`disableAuto`	`disableAuto(): this`	Turn auto-merge off again (`--disable-auto`).
`admin`	`admin(): this`	Merge with administrator privileges (`--admin`).
`deleteBranch`	`deleteBranch(): this`	Delete the branch afterwards (`--delete-branch`).
`subject`	`subject(text: string): this`	The merge commit's subject (`--subject`).
`authorEmail`	`authorEmail(address: string): this`	The merge commit's author email (`--author-email`).
`matchHeadCommit`	`matchHeadCommit(sha: string): this`	Refuse the merge unless the head is still this commit (`--match-head-commit`) — the guard against merging a PR that moved between the check and the merge.

GhPrReadSettings

class

class GhPrReadSettings extends GhWebReadSettings

Base for the pr commands that read one pull request and can print JSON — view and checks — so the operand has one implementation across them.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The pull request — number, URL, or branch; defaults to the current branch's.

GhPrTargetSettings

class

class GhPrTargetSettings extends GhBodySettings

Base for the pr commands that take a pull request and post text — merge, comment, and edit — so the operand and the --body pair have one implementation across them.

Member	Signature	Doc
`selector`	`selector(value: string \| number): this`	The pull request — its number, URL, or branch name. Omit it to act on the PR for the current branch, as gh does.

GhPrViewSettings

class

class GhPrViewSettings extends GhPrReadSettings

Settings for gh pr view.

Member	Signature	Doc
`comments`	`comments(): this`	Include the comments (`--comments`).

GhPullRequestApi

interface

interface GhPullRequestApi

The pull-request operation GhTasks exposes.

Member	Signature	Doc
`pullRequest`	`pullRequest(configure?: unknown): Promise<GhPullRequestResult>`	Open a pull request from `.head(...)` onto `.base(...)`, or return the one already open for that branch. Idempotent on purpose. An unattended job that proposes the same branch twice — because a later step failed and the whole thing ran again — should find its existing proposal rather than fail on it. An existing pull request is returned as it stands: the title and body set here are not written over it, since the caller asked for a proposal to exist and one does. `created` says which happened.
`findPullRequest`	`findPullRequest(configure?: unknown): Promise<GhPullRequestResult \| undefined>`	Find the open pull request from `.head(...)` onto `.base(...)`, without opening one. For a caller that must know whether a proposal already exists before it writes anything — because the answer changes what it should do, not just what it should report. Opening one to find out is not a substitute: by then the branch it would have to prepare has already been written.

GhPullRequestEntry

interface

interface GhPullRequestEntry

One pull request of "./gh.ts".GhTasks.prListEntries.

Member	Signature	Doc
`number?`	`number?: number`	The pull request's number.
`title?`	`title?: string`	Its title.
`state?`	`state?: string`	Its state, as gh reports it: `OPEN`, `CLOSED`, or `MERGED`.
`isDraft?`	`isDraft?: boolean`	Whether it is still a draft.
`headRefName?`	`headRefName?: string`	The branch the changes are on.
`baseRefName?`	`baseRefName?: string`	The branch they would merge into.
`url?`	`url?: string`	Its web URL.
`author?`	`author?: string`	The login of whoever opened it.

GhPullRequestResult

interface

interface GhPullRequestResult

The pull request a GhPullRequestApi.pullRequest call resolved to.

Member	Signature	Doc
`number`	`number: number`	Its number.
`url`	`url: string`	Its web URL.
`created`	`created: boolean`	Whether this call opened it, as opposed to finding one already open. Worth reporting rather than hiding: "proposed" and "already proposed" are different things to a human reading a build log, even though neither is a failure.

GhPullRequestSettings

class

class GhPullRequestSettings

Settings for opening a pull request.

owner/repo and the token fall back to the Actions environment, so a job that already has them needs to name only what it is proposing.

Member	Signature	Doc
`head`	`head(branch: string): this`	The branch being proposed.
`base`	`base(branch: string): this`	The branch it targets.
`title`	`title(text: string): this`	The pull request's title.
`body`	`body(text: string): this`	The pull request's body.
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`head_?`	`head_?: string`	The branch being proposed. Set by `head`.
`base_?`	`base_?: string`	The branch it targets. Set by `base`.
`title_?`	`title_?: string`	The title. Set by `title`.
`body_`	`body_: string`	The body. Set by `body`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhReadSettings

class

class GhReadSettings extends GhCommandSettings

Base for the commands that can print JSON: pr list, pr view, pr checks, issue list, issue view, release list, release view.

gh requires an explicit field list for --json, which is why the value-returning tasks pin one rather than leaving it to the caller.

A …ListEntries reader parses the array --json prints, so .jq(...) and .template(...) — which replace that array with whatever they render — belong on the plain …List task instead.

Member	Signature	Doc
`json`	`json(...fields: string[]): this`	Emit JSON with these fields (`--json`), which gh requires by name — there is no "all fields" form.
`jq`	`jq(expression: string): this`	Filter the JSON with a jq expression (`--jq`).
`template`	`template(text: string): this`	Format the JSON through a Go template (`--template`).

GhReleaseApi

interface

interface GhReleaseApi

The gh release members of "./gh.ts".GhTasks.

Member	Signature	Doc
`releaseCreate`	`releaseCreate(configure?: Configure<GhReleaseCreateSettings>): Promise<CommandOutput>`	Publish a release: `gh release create`.
`releaseList`	`releaseList(configure?: Configure<GhReleaseListSettings>): Promise<CommandOutput>`	List releases: `gh release list`.
`releaseListEntries`	`releaseListEntries(configure?: Configure<GhReleaseListSettings>): Promise<GhReleaseEntry[]>`	The releases as parsed `GhReleaseEntry` values. The `--json` field set is pinned, since gh requires one by name.
`releaseView`	`releaseView(configure?: Configure<GhReleaseViewSettings>): Promise<CommandOutput>`	Show a release: `gh release view`.
`releaseUpload`	`releaseUpload(configure?: Configure<GhReleaseUploadSettings>): Promise<CommandOutput>`	Attach assets to a release: `gh release upload`. Needs the `gh` binary; `"./release_asset.ts".GhReleaseAssetApi.uploadReleaseAsset` is the REST path, which needs a token instead.
`releaseDownload`	`releaseDownload(configure?: Configure<GhReleaseDownloadSettings>): Promise<CommandOutput>`	Download a release's assets: `gh release download`.
`releaseEdit`	`releaseEdit(configure?: Configure<GhReleaseEditSettings>): Promise<CommandOutput>`	Change a release: `gh release edit`.
`releaseDelete`	`releaseDelete(configure?: Configure<GhReleaseDeleteSettings>): Promise<CommandOutput>`	Remove a release: `gh release delete`.

GhReleaseAssetApi

interface

interface GhReleaseAssetApi

The shape of the release-asset task, mixed into GhTasks.

Member	Signature	Doc
`uploadReleaseAsset`	`uploadReleaseAsset(configure?: Configure<GhReleaseAssetSettings>): Promise<GhReleaseAssetResult>`	Attach a file to a GitHub release — the latest release by default, or the one named by `.tag(...)`. Idempotent: an asset the release already carries under the same name is kept as-is (unless `.refresh()` asks for one with different bytes to be replaced), and a repository with no releases resolves to `state: "no-release"` rather than throwing. Needs a token with `contents: write`.

GhReleaseAssetResult

interface

interface GhReleaseAssetResult

What became of a release-asset upload.

Member	Signature	Doc
`state`	`state: uploaded \| refreshed \| already-exists \| no-release`	`uploaded` when the asset was sent; `refreshed` when `.refresh()` found the release carrying different bytes under the name and replaced them; `already-exists` when the release carries an asset of the same name that was kept (nothing was changed); `no-release` when the repository has no release to attach to.
`name`	`name: string`	The asset name the call targeted.
`releaseTag?`	`releaseTag?: string`	The tag of the release the asset belongs to, when one was resolved.
`releaseId?`	`releaseId?: number`	The id of the release the asset belongs to, when one was resolved.
`url?`	`url?: string`	The asset's download URL, when it was uploaded or already present.

GhReleaseAssetSettings

class

class GhReleaseAssetSettings

Settings for GhReleaseAssetApi.uploadReleaseAsset.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	The file to upload (required).
`name`	`name(value: string): this`	The asset's name on the release. Defaults to the file's base name.
`contentType`	`contentType(value: string): this`	The asset's `content-type`. Defaults by extension (`.tar.gz`/`.tgz`, `.zip`, `.json`), then to `application/octet-stream`.
`repo`	`repo(slug: string): this`	The `owner/repo` to upload to. Defaults to `GITHUB_REPOSITORY`.
`tag`	`tag(value: string): this`	Attach to the release with this tag instead of the latest release.
`refresh`	`refresh(): this`	Replace an asset the release already carries when its bytes differ from the file's — compared by the sha256 digest the API reports — instead of keeping it. An asset whose digest matches, or whose digest the API does not report, is still kept: without a comparison to trust, replacement would churn a published release's assets on every run, which is exactly what the default protects. For an asset that must track its source across runs (an extension archive, a docs bundle) on a long-lived release.
`token`	`token(value: string): this`	The token to authenticate with — needs `contents: write`. Defaults to `GITHUB_TOKEN` in the environment, so it never has to reach argv.
`baseUrl`	`baseUrl(url: string): this`	Use a different REST base (GitHub Enterprise Server).
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the Actions environment.
`filePath_`	`filePath_(): string`	The file to upload, or a friendly error naming the missing setting.
`assetName_`	`assetName_(): string`	The effective asset name: the setting, or the file's base name.
`effectiveContentType_`	`effectiveContentType_(): string`	The effective `content-type`: the setting, or inferred by extension.
`file_?`	`file_?: string`	The file to upload. Set by `file`.
`name_?`	`name_?: string`	The asset name on the release. Set by `name`.
`contentType_?`	`contentType_?: string`	The asset's `content-type`. Set by `contentType`.
`repo_?`	`repo_?: string`	`owner/repo` to upload to. Set by `repo`.
`tag_?`	`tag_?: string`	The release tag to attach to. Set by `tag`.
`refresh_`	`refresh_: boolean`	Replace an existing asset whose bytes differ. Set by `refresh`.
`token_?`	`token_?: string`	The token to authenticate with. Set by `token`.
`baseUrl_`	`baseUrl_: string`	REST base URL. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhReleaseCreateSettings

class

class GhReleaseCreateSettings extends GhCommandSettings

Settings for gh release create.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The tag to release (required); gh creates it when it does not exist.
`files`	`files(...paths: PathLike[]): this`	Asset files to attach (positional); repeatable. gh reads a `#label` suffix on a path as the asset's display label.
`title`	`title(text: string): this`	The release title (`--title`).
`notes`	`notes(text: string): this`	The release notes (`--notes`).
`notesFile`	`notesFile(path: PathLike): this`	Read the notes from a file (`--notes-file`); `-` reads standard input.
`generateNotes`	`generateNotes(): this`	Have GitHub write the title and notes (`--generate-notes`).
`notesFromTag`	`notesFromTag(): this`	Take the notes from the tag's annotation (`--notes-from-tag`).
`notesStartTag`	`notesStartTag(name: string): this`	Generate notes starting from this tag (`--notes-start-tag`).
`draft`	`draft(): this`	Save it as a draft rather than publishing (`--draft`).
`prerelease`	`prerelease(): this`	Mark it a prerelease (`--prerelease`).
`latest`	`latest(): this`	Mark it the latest release (`--latest`).
`target`	`target(branchOrSha: string): this`	The branch or commit to tag (`--target`).
`discussionCategory`	`discussionCategory(name: string): this`	Open a discussion in this category (`--discussion-category`).
`verifyTag`	`verifyTag(): this`	Abort unless the tag already exists on the remote (`--verify-tag`).
`failOnNoCommits`	`failOnNoCommits(): this`	Fail when there are no commits since the last release (`--fail-on-no-commits`).

GhReleaseDeleteSettings

class

class GhReleaseDeleteSettings extends GhCommandSettings

Settings for gh release delete.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The release to delete, by tag (required).
`cleanupTag`	`cleanupTag(): this`	Delete the git tag as well (`--cleanup-tag`).
`yes`	`yes(): this`	Skip the confirmation prompt (`--yes`).

GhReleaseDownloadSettings

class

class GhReleaseDownloadSettings extends GhCommandSettings

Settings for gh release download.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The release's tag; gh takes the latest release when it is omitted.
`pattern`	`pattern(...globs: string[]): this`	Only assets matching this glob (`--pattern`); repeatable.
`dir`	`dir(path: PathLike): this`	The directory to download into (`--dir`).
`output`	`output(path: PathLike): this`	Write a single asset to this file (`--output`); `-` writes standard output.
`archive`	`archive(format: zip \| tar.gz): this`	Download the source archive instead of the assets (`--archive`).
`clobber`	`clobber(): this`	Overwrite files that already exist (`--clobber`).
`skipExisting`	`skipExisting(): this`	Leave files that already exist alone (`--skip-existing`).

GhReleaseEditSettings

class

class GhReleaseEditSettings extends GhCommandSettings

Settings for gh release edit.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The release to edit, by its current tag (required).
`newTag`	`newTag(name: string): this`	Move the release to a different tag (`--tag`).
`title`	`title(text: string): this`	Set the title (`--title`).
`notes`	`notes(text: string): this`	Set the notes (`--notes`).
`notesFile`	`notesFile(path: PathLike): this`	Read the notes from a file (`--notes-file`); `-` reads standard input.
`draft`	`draft(): this`	Make it a draft (`--draft`).
`prerelease`	`prerelease(): this`	Mark it a prerelease (`--prerelease`).
`latest`	`latest(): this`	Mark it the latest release (`--latest`).
`target`	`target(branchOrSha: string): this`	Change the target branch or commit (`--target`).
`discussionCategory`	`discussionCategory(name: string): this`	Open a discussion in this category when publishing (`--discussion-category`).
`verifyTag`	`verifyTag(): this`	Abort unless the tag exists on the remote (`--verify-tag`).

GhReleaseEnsureApi

interface

interface GhReleaseEnsureApi

The ensure-release operation GhTasks exposes.

Member	Signature	Doc
`ensureRelease`	`ensureRelease(configure?: Configure<GhReleaseEnsureSettings>): Promise<GhReleaseEnsureResult>`	Publish a release for `.tag(...)` unless it already has one. Reads the tag's release first and returns `state: "exists"` when there is one, writing nothing — so an unattended pipeline can run this on every push without overwriting notes a maintainer wrote by hand. Needs a token with `contents: write`.

GhReleaseEnsureResult

interface

interface GhReleaseEnsureResult

What became of a GhReleaseEnsureApi.ensureRelease call.

Member	Signature	Doc
`state`	`state: created \| exists`	`created` when this call published the release; `exists` when the tag already had one and nothing was written.
`tag`	`tag: string`	The tag the release is attached to.
`releaseId`	`releaseId: number`	The release's id.
`url`	`url: string`	The release's page, for a log line a human can follow.

GhReleaseEnsureSettings

class

class GhReleaseEnsureSettings

Settings for ensuring a release exists.

owner/repo and the token fall back to the Actions environment, so a job that already has them names only the release.

Member	Signature	Doc
`tag`	`tag(value: string): this`	The tag to release (required). It should already exist. GitHub creates a missing tag on the default branch rather than refusing, so a typo here publishes a tag as well as a release — which is why the caller that reconciles a backlog reads its tags from git rather than composing them.
`name`	`name(text: string): this`	The release title (required), e.g. `Zuke Build v1.2.3`.
`body`	`body(text: string): this`	The release notes (required); pass `""` for a release with none.
`latest`	`latest(value?: boolean): this`	Move the repository's "Latest release" pointer onto this release. Off unless asked, which is the opposite of GitHub's own default — it treats a new release as latest unless told otherwise. The default is inverted because the first thing this is used for is back-filling releases a pipeline missed, and those are created oldest-first: taking GitHub's default would walk the pointer backwards through the backlog and leave it on whichever release was created last, which is the oldest one. Naming it explicitly costs the one caller that wants it a method call, and costs the ones that do not want it nothing at all.
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with — needs `contents: write`. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`tag_?`	`tag_?: string`	The tag to release. Set by `tag`.
`name_?`	`name_?: string`	The release title. Set by `name`.
`body_?`	`body_?: string`	The release notes. Set by `body`.
`latest_`	`latest_: boolean`	Whether to move the "Latest release" pointer. Set by `latest`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhReleaseEntry

interface

interface GhReleaseEntry

One release of "./gh.ts".GhTasks.releaseListEntries.

Member	Signature	Doc
`tagName?`	`tagName?: string`	The release's tag.
`name?`	`name?: string`	Its name, which GitHub calls the title.
`isDraft?`	`isDraft?: boolean`	Whether it is still a draft.
`isPrerelease?`	`isPrerelease?: boolean`	Whether it is marked a prerelease.
`isLatest?`	`isLatest?: boolean`	Whether it is the latest release.
`publishedAt?`	`publishedAt?: string`	When it was published, ISO 8601; absent while it is a draft.

GhReleaseLatestApi

interface

interface GhReleaseLatestApi

The mark-latest operation GhTasks exposes.

Member	Signature	Doc
`markReleaseLatest`	`markReleaseLatest(configure?: Configure<GhReleaseLatestSettings>): Promise<GhReleaseLatestResult>`	Point the repository's "Latest release" at the release for `.tag(...)`. Idempotent, and quiet about it: a pointer already on the tag's release is left untouched rather than re-written, so an unattended pipeline can run this unconditionally without churning the release's audit history. A tag with no release resolves to `state: "no-release"` rather than throwing — the release may be cut by a later, human step — while a tag that does not exist at all is an error, because the caller named it. Needs a token with `contents: write`.

GhReleaseLatestResult

interface

interface GhReleaseLatestResult

What became of a GhReleaseLatestApi.markReleaseLatest call.

Member	Signature	Doc
`state`	`state: marked \| already-latest \| no-release`	`marked` when the pointer was moved onto the tag's release; `already-latest` when it was there before the call (nothing was written); `no-release` when the tag has no release to point at — an ordinary outcome for a tag whose release is created by a later, human step.
`tag`	`tag: string`	The tag the call targeted.
`releaseId?`	`releaseId?: number`	The id of the tag's release, when one was resolved.

GhReleaseLatestSettings

class

class GhReleaseLatestSettings

Settings for marking a release as latest.

owner/repo and the token fall back to the Actions environment, so a job that already has them needs to name only the tag.

Member	Signature	Doc
`tag`	`tag(value: string): this`	The tag whose release the pointer should name (required).
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with — needs `contents: write`. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`tag_?`	`tag_?: string`	The tag whose release becomes latest. Set by `tag`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhReleaseListSettings

class

class GhReleaseListSettings extends GhReadSettings

Settings for gh release list.

Member	Signature	Doc
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.
`order`	`order(direction: asc \| desc): this`	The order they come back in (`--order`): `asc` or `desc`.
`excludeDrafts`	`excludeDrafts(): this`	Leave out drafts (`--exclude-drafts`).
`excludePreReleases`	`excludePreReleases(): this`	Leave out prereleases (`--exclude-pre-releases`).

GhReleaseUploadSettings

class

class GhReleaseUploadSettings extends GhCommandSettings

Settings for gh release upload.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The release's tag (required).
`files`	`files(...paths: PathLike[]): this`	Asset files to attach (required); repeatable. gh reads a `#label` suffix on a path as the asset's display label.
`clobber`	`clobber(): this`	Replace an asset of the same name (`--clobber`).

GhReleaseViewSettings

class

class GhReleaseViewSettings extends GhWebReadSettings

Settings for gh release view.

Member	Signature	Doc
`tag`	`tag(name: string): this`	The release's tag; gh shows the latest release when it is omitted.

GhRepoApi

interface

interface GhRepoApi

The gh repo members of "./gh.ts".GhTasks.

Member	Signature	Doc
`repoClone`	`repoClone(configure?: Configure<GhRepoCloneSettings>): Promise<CommandOutput>`	Clone a repository: `gh repo clone`.
`repoCreate`	`repoCreate(configure?: Configure<GhRepoCreateSettings>): Promise<CommandOutput>`	Create a repository: `gh repo create`.
`repoView`	`repoView(configure?: Configure<GhRepoViewSettings>): Promise<CommandOutput>`	Show a repository: `gh repo view`.
`repoList`	`repoList(configure?: Configure<GhRepoListSettings>): Promise<CommandOutput>`	List repositories: `gh repo list`.
`repoListEntries`	`repoListEntries(configure?: Configure<GhRepoListSettings>): Promise<GhRepositoryEntry[]>`	The repositories as parsed `GhRepositoryEntry` values. The `--json` field set is pinned, since gh requires one by name.
`repoFork`	`repoFork(configure?: Configure<GhRepoForkSettings>): Promise<CommandOutput>`	Fork a repository: `gh repo fork`.
`repoSync`	`repoSync(configure?: Configure<GhRepoSyncSettings>): Promise<CommandOutput>`	Bring a fork up to date: `gh repo sync`.
`repoEdit`	`repoEdit(configure?: Configure<GhRepoEditSettings>): Promise<CommandOutput>`	Change a repository's settings: `gh repo edit`.
`repoRename`	`repoRename(configure?: Configure<GhRepoRenameSettings>): Promise<CommandOutput>`	Rename a repository: `gh repo rename`.
`repoArchive`	`repoArchive(configure?: Configure<GhRepoArchiveSettings>): Promise<CommandOutput>`	Archive or unarchive a repository: `gh repo archive`/`unarchive`.
`repoDelete`	`repoDelete(configure?: Configure<GhRepoDeleteSettings>): Promise<CommandOutput>`	Delete a repository: `gh repo delete`. Needs the `delete_repo` scope.
`repoSetDefault`	`repoSetDefault(configure?: Configure<GhRepoSetDefaultSettings>): Promise<CommandOutput>`	Choose the repository gh acts on by default: `gh repo set-default`.

GhRepoArchiveSettings

class

class GhRepoArchiveSettings extends GhRepoCommandSettings

Settings for gh repo archive and gh repo unarchive.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository; gh acts on the current one otherwise.
`unarchive`	`unarchive(): this`	Restore an archived repository instead — `gh repo unarchive`.
`yes`	`yes(): this`	Skip the confirmation gh otherwise prompts for (`--yes`).

GhRepoCloneSettings

class

class GhRepoCloneSettings extends GhRepoCommandSettings

Settings for gh repo clone.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository, as `owner/name` or a URL (required).
`directory`	`directory(path: PathLike): this`	The directory to clone into; gh names it after the repository otherwise.
`upstreamRemoteName`	`upstreamRemoteName(name: string): this`	The remote name for a fork's parent (`--upstream-remote-name`).
`noUpstream`	`noUpstream(): this`	Do not add the upstream remote when cloning a fork (`--no-upstream`).
`gitArgs`	`gitArgs(...args: string[]): this`	Flags for the underlying `git clone`, which gh takes after a `--` separator — `.gitArgs("--depth=1")` for a shallow clone.

GhRepoCommandSettings

class

class GhRepoCommandSettings extends GhCommandSettings

Base for the gh repo commands that neither print JSON nor take --repo. GhRepoListSettings and GhRepoViewSettings do print JSON, so they extend the read bases and call refuseRepoFlag themselves.

GhRepoCreateSettings

class

class GhRepoCreateSettings extends GhRepoCommandSettings

Settings for gh repo create.

Member	Signature	Doc
`name`	`name(value: string): this`	The repository's name, or `owner/name` to create it elsewhere (required).
`visibility`	`visibility(value: GhRepoVisibility): this`	How visible it is: `--public`, `--private`, or `--internal` (required).
`description`	`description(text: string): this`	Its description (`--description`).
`homepage`	`homepage(url: string): this`	Its homepage (`--homepage`).
`team`	`team(name: string): this`	Grant an organization team access (`--team`).
`template`	`template(slug: string): this`	Base it on a template repository (`--template`).
`gitignore`	`gitignore(name: string): this`	Start from a gitignore template (`--gitignore`).
`license`	`license(name: string): this`	Add an open-source license (`--license`).
`source`	`source(path: PathLike): this`	Create it from a local repository (`--source`).
`remote`	`remote(name: string): this`	The remote name for the new repository (`--remote`).
`clone`	`clone(): this`	Clone it after creating it (`--clone`).
`push`	`push(): this`	Push the local commits to it (`--push`).
`addReadme`	`addReadme(): this`	Add a README (`--add-readme`).
`includeAllBranches`	`includeAllBranches(): this`	Copy every branch of the template, not just its default (`--include-all-branches`).
`disableIssues`	`disableIssues(): this`	Turn issues off (`--disable-issues`).
`disableWiki`	`disableWiki(): this`	Turn the wiki off (`--disable-wiki`).

GhRepoDeleteSettings

class

class GhRepoDeleteSettings extends GhRepoCommandSettings

Settings for gh repo delete.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository to delete, as `owner/name` (required — see below).
`yes`	`yes(): this`	Skip the confirmation a delete otherwise prompts for (`--yes`).

GhRepoEditSettings

class

class GhRepoEditSettings extends GhRepoCommandSettings

Settings for gh repo edit.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository to edit; gh edits the current one otherwise.
`description`	`description(text: string): this`	Set the description (`--description`).
`homepage`	`homepage(url: string): this`	Set the homepage (`--homepage`).
`defaultBranch`	`defaultBranch(name: string): this`	Set the default branch (`--default-branch`).
`visibility`	`visibility(value: GhRepoVisibility): this`	Change the visibility (`--visibility`), which needs `acceptVisibilityChangeConsequences`.
`acceptVisibilityChangeConsequences`	`acceptVisibilityChangeConsequences(): this`	Acknowledge what a visibility change does (`--accept-visibility-change-consequences`).
`addTopic`	`addTopic(...names: string[]): this`	Add a topic (`--add-topic`); repeatable.
`removeTopic`	`removeTopic(...names: string[]): this`	Remove a topic (`--remove-topic`); repeatable.
`enableIssues`	`enableIssues(enabled?: boolean): this`	Turn issues on or off (`--enable-issues`).
`enableWiki`	`enableWiki(enabled?: boolean): this`	Turn the wiki on or off (`--enable-wiki`).
`enableProjects`	`enableProjects(enabled?: boolean): this`	Turn projects on or off (`--enable-projects`).
`enableDiscussions`	`enableDiscussions(enabled?: boolean): this`	Turn discussions on or off (`--enable-discussions`).
`enableAutoMerge`	`enableAutoMerge(enabled?: boolean): this`	Turn auto-merge on or off (`--enable-auto-merge`).
`enableMergeCommit`	`enableMergeCommit(enabled?: boolean): this`	Allow or forbid merge commits (`--enable-merge-commit`).
`enableSquashMerge`	`enableSquashMerge(enabled?: boolean): this`	Allow or forbid squash merges (`--enable-squash-merge`).
`enableRebaseMerge`	`enableRebaseMerge(enabled?: boolean): this`	Allow or forbid rebase merges (`--enable-rebase-merge`).
`deleteBranchOnMerge`	`deleteBranchOnMerge(enabled?: boolean): this`	Delete the head branch after a merge, or stop (`--delete-branch-on-merge`).
`allowForking`	`allowForking(enabled?: boolean): this`	Allow or forbid forking (`--allow-forking`).
`allowUpdateBranch`	`allowUpdateBranch(enabled?: boolean): this`	Allow or forbid updating a pull request branch (`--allow-update-branch`).
`enableSecretScanning`	`enableSecretScanning(enabled?: boolean): this`	Turn secret scanning on or off (`--enable-secret-scanning`).
`enableSecretScanningPushProtection`	`enableSecretScanningPushProtection(enabled?: boolean): this`	Turn push protection on or off (`--enable-secret-scanning-push-protection`).

GhRepoForkSettings

class

class GhRepoForkSettings extends GhRepoCommandSettings

Settings for gh repo fork.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository to fork; gh forks the current one otherwise.
`org`	`org(name: string): this`	Create the fork in an organization (`--org`).
`forkName`	`forkName(value: string): this`	Name the fork something else (`--fork-name`).
`remoteName`	`remoteName(value: string): this`	The remote name to add for the fork (`--remote-name`).
`clone`	`clone(): this`	Clone the fork after creating it (`--clone`).
`remote`	`remote(): this`	Add a git remote for the fork (`--remote`).
`defaultBranchOnly`	`defaultBranchOnly(): this`	Fork only the default branch (`--default-branch-only`).
`gitArgs`	`gitArgs(...args: string[]): this`	Flags for the underlying `git clone`, passed after a `--` separator.

GhRepoListSettings

class

class GhRepoListSettings extends GhReadSettings

Settings for gh repo list.

Member	Signature	Doc
`owner`	`owner(login: string): this`	Whose repositories to list; gh lists your own when it is omitted.
`language`	`language(name: string): this`	Filter by primary language (`--language`).
`topic`	`topic(...names: string[]): this`	Filter by topic (`--topic`); repeatable.
`visibility`	`visibility(value: GhRepoVisibility): this`	Filter by visibility (`--visibility`).
`archived`	`archived(): this`	Only archived repositories (`--archived`).
`noArchived`	`noArchived(): this`	Leave archived repositories out (`--no-archived`).
`fork`	`fork(): this`	Only forks (`--fork`).
`source`	`source(): this`	Only repositories that are not forks (`--source`).
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 30.

GhRepoRenameSettings

class

class GhRepoRenameSettings extends GhCommandSettings

Settings for gh repo rename.

Member	Signature	Doc
`newName`	`newName(value: string): this`	The repository's new name, without the owner (required).
`yes`	`yes(): this`	Skip the confirmation a rename otherwise prompts for (`--yes`).

GhRepoSetDefaultSettings

class

class GhRepoSetDefaultSettings extends GhRepoCommandSettings

Settings for gh repo set-default.

Member	Signature	Doc
`repository`	`repository(slugOrRemote: string): this`	The repository to make the default, as `owner/name` or a remote name.
`unset`	`unset(): this`	Forget the current default instead (`--unset`).
`view`	`view(): this`	Report the current default instead (`--view`).

GhRepositoryEntry

interface

interface GhRepositoryEntry

One repository of "./gh.ts".GhTasks.repoListEntries.

Member	Signature	Doc
`name?`	`name?: string`	The repository's name, without the owner.
`nameWithOwner?`	`nameWithOwner?: string`	Its full `owner/name`.
`description?`	`description?: string`	Its description.
`isPrivate?`	`isPrivate?: boolean`	Whether it is private.
`isFork?`	`isFork?: boolean`	Whether it is a fork.
`isArchived?`	`isArchived?: boolean`	Whether it is archived.
`url?`	`url?: string`	Its web URL.
`updatedAt?`	`updatedAt?: string`	When it was last updated, ISO 8601.

GhRepoSyncSettings

class

class GhRepoSyncSettings extends GhRepoCommandSettings

Settings for gh repo sync.

Member	Signature	Doc
`destination`	`destination(slug: string): this`	The repository to update; gh syncs the local one otherwise.
`source`	`source(slug: string): this`	Where to sync from (`--source`); gh uses the fork's parent otherwise.
`branch`	`branch(name: string): this`	The branch to sync (`--branch`); gh uses the default branch otherwise.
`force`	`force(): this`	Hard-reset the destination branch onto the source (`--force`).

GhRepoViewSettings

class

class GhRepoViewSettings extends GhWebReadSettings

Settings for gh repo view.

Member	Signature	Doc
`repository`	`repository(slug: string): this`	The repository, as `owner/name`; gh uses the current one otherwise.
`branch`	`branch(name: string): this`	View a particular branch (`--branch`).

GhRepoVisibility

type

type GhRepoVisibility = public | private | internal

How visible a repository is (--visibility).

GhRunApi

interface

interface GhRunApi

The gh run members of "./gh.ts".GhTasks.

Member	Signature	Doc
`runList`	`runList(configure?: Configure<GhRunListSettings>): Promise<CommandOutput>`	List workflow runs: `gh run list`.
`runListEntries`	`runListEntries(configure?: Configure<GhRunListSettings>): Promise<GhRunEntry[]>`	The runs as parsed `GhRunEntry` values — the reader a build branches on. The `--json` field set is pinned, since gh requires one by name.
`runView`	`runView(configure?: Configure<GhRunViewSettings>): Promise<CommandOutput>`	Show a run: `gh run view`.
`runRerun`	`runRerun(configure?: Configure<GhRunRerunSettings>): Promise<CommandOutput>`	Rerun a run, or its failed jobs: `gh run rerun`.
`runCancel`	`runCancel(configure?: Configure<GhRunCancelSettings>): Promise<CommandOutput>`	Stop a run: `gh run cancel`.
`runDelete`	`runDelete(configure?: Configure<GhRunDeleteSettings>): Promise<CommandOutput>`	Remove a run: `gh run delete`.
`runDownload`	`runDownload(configure?: Configure<GhRunDownloadSettings>): Promise<CommandOutput>`	Fetch a run's artifacts: `gh run download`.
`runWatch`	`runWatch(configure?: Configure<GhRunWatchSettings>): Promise<CommandOutput>`	Follow a run until it finishes: `gh run watch`. A target that watches blocks until Actions is done, so pair it with `.killAfter(...)` unless the wait is the point.

GhRunCancelSettings

class

class GhRunCancelSettings extends GhRunTargetSettings

Settings for gh run cancel.

Member	Signature	Doc
`force`	`force(): this`	Cancel a run the ordinary request will not stop (`--force`).

GhRunDeleteSettings

class

class GhRunDeleteSettings extends GhRunTargetSettings

Settings for gh run delete.

GhRunDownloadSettings

class

class GhRunDownloadSettings extends GhRunTargetSettings

Settings for gh run download.

Member	Signature	Doc
`name`	`name(...names: string[]): this`	Only artifacts with this exact name (`--name`); repeatable.
`pattern`	`pattern(...globs: string[]): this`	Only artifacts matching this glob (`--pattern`); repeatable.
`dir`	`dir(path: PathLike): this`	The directory to download into (`--dir`); gh's default is the cwd.

GhRunEntry

interface

interface GhRunEntry

One workflow run of "./gh.ts".GhTasks.runListEntries.

Member	Signature	Doc
`databaseId?`	`databaseId?: number`	The run's numeric id — what every other `run` command takes.
`number?`	`number?: number`	Its number within its workflow.
`displayTitle?`	`displayTitle?: string`	The title GitHub displays, usually the head commit's subject.
`workflowName?`	`workflowName?: string`	The name of the workflow it ran.
`headBranch?`	`headBranch?: string`	The branch it ran on.
`event?`	`event?: string`	The event that triggered it.
`status?`	`status?: string`	Its status, as gh reports it: `completed`, `in_progress`, …
`conclusion?`	`conclusion?: string`	Its conclusion once complete: `success`, `failure`, …
`url?`	`url?: string`	Its web URL.
`createdAt?`	`createdAt?: string`	When it was created, ISO 8601.

GhRunListSettings

class

class GhRunListSettings extends GhReadSettings

Settings for gh run list.

Member	Signature	Doc
`all`	`all(): this`	Include runs of disabled workflows (`--all`).
`branch`	`branch(name: string): this`	Filter by branch (`--branch`).
`commit`	`commit(sha: string): this`	Filter by the commit that triggered them (`--commit`).
`created`	`created(query: string): this`	Filter by creation date (`--created`), in GitHub's date-query syntax.
`event`	`event(name: string): this`	Filter by the event that triggered them (`--event`).
`status`	`status(value: GhRunStatus): this`	Filter by status or conclusion (`--status`).
`user`	`user(login: string): this`	Filter by the user who triggered them (`--user`).
`workflow`	`workflow(nameOrId: string): this`	Filter by workflow, by name, id, or file name (`--workflow`).
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 20.

GhRunRerunSettings

class

class GhRunRerunSettings extends GhRunTargetSettings

Settings for gh run rerun.

Member	Signature	Doc
`failed`	`failed(): this`	Rerun only the failed jobs and their dependencies (`--failed`).
`job`	`job(jobId: string \| number): this`	Rerun one job and its dependencies (`--job`), by job id.
`debug`	`debug(): this`	Rerun with debug logging enabled (`--debug`).

GhRunStatus

type

type GhRunStatus = queued | completed | in_progress | requested | waiting | pending | action_required | cancelled | failure | neutral | skipped | stale | startup_failure | success | timed_out

The status gh run list --status filters by: the run's state while it is going, then the conclusion it settles on.

GhRunTargetSettings

class

class GhRunTargetSettings extends GhCommandSettings

Base for the run commands that name one run. gh prompts for a run when the operand is omitted, so unlike a pull request there is no useful default.

Member	Signature	Doc
`selector`	`selector(runId: string \| number): this`	The run — its id (required).

GhRunViewSettings

class

class GhRunViewSettings extends GhWebReadSettings

Settings for gh run view.

Member	Signature	Doc
`selector`	`selector(runId: string \| number): this`	The run — its id; gh shows a picker without one.
`attempt`	`attempt(number: number): this`	View an earlier attempt (`--attempt`).
`job`	`job(jobId: string \| number): this`	View one job of the run (`--job`), by job id.
`log`	`log(): this`	Print the full log (`--log`).
`logFailed`	`logFailed(): this`	Print only the failed steps' log (`--log-failed`).
`exitStatus`	`exitStatus(): this`	Exit non-zero when the run failed (`--exit-status`).
`verbose`	`verbose(): this`	Include the individual job steps (`--verbose`).

GhRunWatchSettings

class

class GhRunWatchSettings extends GhRunTargetSettings

Settings for gh run watch.

Member	Signature	Doc
`compact`	`compact(): this`	Report only the relevant and failed steps (`--compact`).
`exitStatus`	`exitStatus(): this`	Exit non-zero when the run fails (`--exit-status`).
`interval`	`interval(seconds: number): this`	Seconds between refreshes (`--interval`); gh's default is 3.

GhSarifApi

interface

interface GhSarifApi

The shape of the SARIF task, mixed into GhTasks.

Member	Signature	Doc
`uploadSarif`	`uploadSarif(configure?: Configure<GhSarifSettings>): Promise<GhSarifUploadResult>`	Upload a SARIF report to GitHub code scanning, so its findings land in the repository's Security tab. Needs a token with `security-events: write`.

GhSarifSettings

class

class GhSarifSettings

Settings for GhSarifApi.uploadSarif.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	The SARIF report to upload (required).
`repo`	`repo(slug: string): this`	The `owner/repo` to upload for. Defaults to `GITHUB_REPOSITORY`.
`commit`	`commit(sha: string): this`	The commit SHA the results describe. Defaults to `GITHUB_SHA`.
`ref`	`ref(ref: string): this`	The full ref the results describe (`refs/heads/main`). Defaults to `GITHUB_REF`.
`token`	`token(value: string): this`	The token to authenticate with — needs `security-events: write`. Defaults to `GITHUB_TOKEN` in the environment, so it never has to reach argv.
`checkoutUri`	`checkoutUri(uri: string): this`	The URI of the checkout the results are relative to (`file:///…`).
`baseUrl`	`baseUrl(url: string): this`	Use a different REST base (GitHub Enterprise Server).
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the Actions environment.
`body_`	`body_(): Promise<Record<string, string>>`	The request body. The `sarif` field is the report gzipped then base64'd, which is what the endpoint accepts — a plain JSON body is rejected.
`file_?`	`file_?: string`	The SARIF file to upload. Set by `file`.
`repo_?`	`repo_?: string`	`owner/repo` to upload for. Set by `repo`.
`commit_?`	`commit_?: string`	The commit the results describe. Set by `commit`.
`ref_?`	`ref_?: string`	The ref the results describe. Set by `ref`.
`token_?`	`token_?: string`	The token to authenticate with. Set by `token`.
`checkoutUri_?`	`checkoutUri_?: string`	Where the checkout that produced the results lives. Set by `checkoutUri`.
`baseUrl_`	`baseUrl_: string`	REST base URL. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhSarifUploadResult

interface

interface GhSarifUploadResult

What GitHub returns for an accepted SARIF upload.

Member	Signature	Doc
`id`	`id: string`	The opaque id of the upload, for polling its processing status.
`url`	`url: string`	The URL that reports whether GitHub finished processing the report.

GhScopeVisibility

type

type GhScopeVisibility = all | private | selected

Who an organization value is visible to (--visibility).

GhSecretApi

interface

interface GhSecretApi

The gh secret members of "./gh.ts".GhTasks.

Member	Signature	Doc
`secretSet`	`secretSet(configure?: Configure<GhSecretSetSettings>): Promise<CommandOutput>`	Store a secret: `gh secret set`. A value passed as `.body(...)` becomes an argv entry and is readable in a process listing — see the module docs of `"./secret.ts".GhSecretSetSettings` for the alternatives.
`secretList`	`secretList(configure?: Configure<GhSecretListSettings>): Promise<CommandOutput>`	List the secrets' names: `gh secret list`.
`secretListEntries`	`secretListEntries(configure?: Configure<GhSecretListSettings>): Promise<GhSecretEntry[]>`	The secrets as parsed `GhSecretEntry` values — names and metadata; GitHub never returns a secret's value.
`secretDelete`	`secretDelete(configure?: Configure<GhSecretDeleteSettings>): Promise<CommandOutput>`	Remove a secret: `gh secret delete`.

GhSecretApp

type

type GhSecretApp = actions | agents | codespaces | dependabot

Which application reads the secret (--app).

GhSecretDeleteSettings

class

class GhSecretDeleteSettings extends GhSecretScopeSettings

Settings for gh secret delete.

Member	Signature	Doc
`name`	`name(value: string): this`	The secret's name (required).

GhSecretEntry

interface

interface GhSecretEntry

One secret of "./gh.ts".GhTasks.secretListEntries. GitHub never returns a secret's value, so an entry is its name and its metadata.

Member	Signature	Doc
`name?`	`name?: string`	The secret's name.
`updatedAt?`	`updatedAt?: string`	When it was last updated, ISO 8601.
`visibility?`	`visibility?: string`	The visibility of an organization secret.

GhSecretListSettings

class

class GhSecretListSettings extends GhReadSettings

Settings for gh secret list.

Member	Signature	Doc
`app`	`app(name: GhSecretApp): this`	Which application's secrets to list (`--app`).
`org`	`org(name: string): this`	List an organization's secrets (`--org`).
`environment`	`environment(name: string): this`	List an environment's secrets (`--env`).
`user`	`user(): this`	List your own secrets (`--user`).

GhSecretScopeSettings

class

class GhSecretScopeSettings extends GhCommandSettings

Base for the secret commands that name one scope: the application, and whether the secret belongs to a repository, an organization, an environment, or the authenticated user.

Member	Signature	Doc
`app`	`app(name: GhSecretApp): this`	Which application reads it (`--app`); gh's default is `actions`.
`org`	`org(name: string): this`	Scope it to an organization (`--org`).
`environment`	`environment(name: string): this`	Scope it to a deployment environment (`--env`).
`user`	`user(): this`	Scope it to the authenticated user (`--user`).
`repositories`	`repositories(...names: string[]): this`	Share an organization secret with these repositories (`--repos`).
`visibility`	`visibility(value: GhScopeVisibility): this`	The visibility of an organization secret (`--visibility`).

GhSecretSetSettings

class

class GhSecretSetSettings extends GhSecretScopeSettings

Settings for gh secret set.

Member	Signature	Doc
`name`	`name(value: string): this`	The secret's name (required).
`body`	`body(value: string): this`	The secret's value (`--body`). Omit it and gh reads standard input, which keeps the value out of the process's arguments — see the module docs.
`envFile`	`envFile(path: PathLike): this`	Read names and values from a dotenv file (`--env-file`).
`noStore`	`noStore(): this`	Print the encrypted value instead of storing it (`--no-store`).
`noReposSelected`	`noReposSelected(): this`	Share the organization secret with no repositories (`--no-repos-selected`).

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

GhTagSettings

class

class GhTagSettings

Settings for pointing a tag at a commit.

Member	Signature	Doc
`name`	`name(value: string): this`	The tag name, e.g. `v1.2.3`.
`commit`	`commit(sha: string): this`	The commit SHA to tag. Defaults to `GITHUB_SHA`.
`message`	`message(text: string): this`	The annotation message. Defaults to the tag name.
`move`	`move(): this`	Move the tag if it already exists, rather than failing. Forced by necessity: pointing a major tag at a newer release is a non-fast-forward by definition. A tag that does not exist yet is created, since for the first release of a major those are the same intent.
`repo`	`repo(slug: string): this`	`owner/repo`. Defaults to `GITHUB_REPOSITORY`.
`token`	`token(value: string): this`	The token to authenticate with. Defaults to `GITHUB_TOKEN`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`repoSlug_`	`repoSlug_(): string`	The effective `owner/repo`, from the setting or the environment.
`authToken_`	`authToken_(): string`	The effective token, from the setting or the environment.
`name_?`	`name_?: string`	The tag name. Set by `name`.
`commit_?`	`commit_?: string`	The commit the tag points at. Set by `commit`.
`message_?`	`message_?: string`	The annotation message. Set by `message`.
`move_`	`move_: boolean`	Whether to move an existing tag. Set by `move`.
`repo_?`	`repo_?: string`	`owner/repo`. Set by `repo`.
`token_?`	`token_?: string`	The token. Set by `token`.
`baseUrl_`	`baseUrl_: string`	The API root. Set by `baseUrl`.
`fetch_`	`fetch_: fetch`	The `fetch` implementation. Set by `fetch`.

GhTasks

const

const GhTasks: GhTasksApi

Typed task functions for GitHub: the gh CLI and the REST-only operations.

GhTasksApi

interface

interface GhTasksApi

The shape of GhTasks: the gh CLI plus the GitHub operations that have no CLI subcommand (see GhAppTokenApi, GhSarifApi) and would otherwise force a build back to a marketplace action.

Member	Signature	Doc
`run`	`run(configure?: Configure<GhSettings>): Promise<CommandOutput>`	Run a `gh` command.
`api`	`api(endpoint: string, configure?: Configure<GhApiSettings>): Promise<CommandOutput>`	Call a REST endpoint through `gh api`, with the user's `gh` credentials — for operations that have no CLI verb, e.g. starring a repository: `GhTasks.api("user/starred/zuke-build/zuke", (s) => s.method("PUT"))`.

GhVariableApi

interface

interface GhVariableApi

The gh variable members of "./gh.ts".GhTasks.

Member	Signature	Doc
`variableSet`	`variableSet(configure?: Configure<GhVariableSetSettings>): Promise<CommandOutput>`	Store a variable: `gh variable set`.
`variableGet`	`variableGet(configure?: Configure<GhVariableGetSettings>): Promise<CommandOutput>`	Read a variable: `gh variable get`.
`variableValue`	`variableValue(configure?: Configure<GhVariableGetSettings>): Promise<string>`	A variable's value, with the trailing newline gh prints removed.
`variableList`	`variableList(configure?: Configure<GhVariableListSettings>): Promise<CommandOutput>`	List variables: `gh variable list`.
`variableListEntries`	`variableListEntries(configure?: Configure<GhVariableListSettings>): Promise<GhVariableEntry[]>`	The variables as parsed `GhVariableEntry` values, values included — a variable is not a secret.
`variableDelete`	`variableDelete(configure?: Configure<GhVariableDeleteSettings>): Promise<CommandOutput>`	Remove a variable: `gh variable delete`.

GhVariableDeleteSettings

class

class GhVariableDeleteSettings extends GhCommandSettings

Settings for gh variable delete.

Member	Signature	Doc
`name`	`name(value: string): this`	The variable's name (required).
`org`	`org(name: string): this`	Delete an organization variable (`--org`).
`environment`	`environment(name: string): this`	Delete an environment variable (`--env`).

GhVariableEntry

interface

interface GhVariableEntry

One variable of "./gh.ts".GhTasks.variableListEntries.

Member	Signature	Doc
`name?`	`name?: string`	The variable's name.
`value?`	`value?: string`	Its value, which GitHub returns in the clear.
`updatedAt?`	`updatedAt?: string`	When it was last updated, ISO 8601.
`visibility?`	`visibility?: string`	The visibility of an organization variable.

GhVariableGetSettings

class

class GhVariableGetSettings extends GhReadSettings

Settings for gh variable get.

Member	Signature	Doc
`name`	`name(value: string): this`	The variable's name (required).
`org`	`org(name: string): this`	Read an organization variable (`--org`).
`environment`	`environment(name: string): this`	Read an environment variable (`--env`).

GhVariableListSettings

class

class GhVariableListSettings extends GhReadSettings

Settings for gh variable list.

Member	Signature	Doc
`org`	`org(name: string): this`	List an organization's variables (`--org`).
`environment`	`environment(name: string): this`	List an environment's variables (`--env`).

GhVariableSetSettings

class

class GhVariableSetSettings extends GhCommandSettings

Settings for gh variable set.

Member	Signature	Doc
`name`	`name(value: string): this`	The variable's name (required).
`body`	`body(value: string): this`	Its value (`--body`); omit it and gh reads standard input.
`envFile`	`envFile(path: PathLike): this`	Read names and values from a dotenv file (`--env-file`).
`org`	`org(name: string): this`	Scope it to an organization (`--org`).
`environment`	`environment(name: string): this`	Scope it to a deployment environment (`--env`).
`repositories`	`repositories(...names: string[]): this`	Share an organization variable with these repositories (`--repos`).
`visibility`	`visibility(value: GhScopeVisibility): this`	The visibility of an organization variable (`--visibility`).

GhWebReadSettings

class

class GhWebReadSettings extends GhReadSettings

Base for the read commands that also take --web: every one of them except release list, which gh gives no browser view. Keeping .web() here rather than on GhReadSettings is what stops a build offering a flag gh would reject.

Member	Signature	Doc
`web`	`web(): this`	Open the result in a browser instead of printing it (`--web`). A build has no browser, so this is for a developer running the target by hand.

GhWorkflowApi

interface

interface GhWorkflowApi

The gh workflow members of "./gh.ts".GhTasks.

Member	Signature	Doc
`workflowList`	`workflowList(configure?: Configure<GhWorkflowListSettings>): Promise<CommandOutput>`	List workflows: `gh workflow list`.
`workflowListEntries`	`workflowListEntries(configure?: Configure<GhWorkflowListSettings>): Promise<GhWorkflowEntry[]>`	The workflows as parsed `GhWorkflowEntry` values. The `--json` field set is pinned, since gh requires one by name.
`workflowView`	`workflowView(configure?: Configure<GhWorkflowViewSettings>): Promise<CommandOutput>`	Show a workflow, or its YAML: `gh workflow view`.
`workflowRun`	`workflowRun(configure?: Configure<GhWorkflowRunSettings>): Promise<CommandOutput>`	Dispatch a workflow: `gh workflow run`. This returns once the dispatch is accepted; `"./workflow.ts".githubWorkflow` is the wait trigger that suspends the build until the run finishes.
`workflowEnable`	`workflowEnable(configure?: Configure<GhWorkflowEnableSettings>): Promise<CommandOutput>`	Turn a workflow on: `gh workflow enable`.
`workflowDisable`	`workflowDisable(configure?: Configure<GhWorkflowDisableSettings>): Promise<CommandOutput>`	Turn a workflow off: `gh workflow disable`.

GhWorkflowDisableSettings

class

class GhWorkflowDisableSettings extends GhWorkflowTargetSettings

Settings for gh workflow disable.

GhWorkflowEnableSettings

class

class GhWorkflowEnableSettings extends GhWorkflowTargetSettings

Settings for gh workflow enable.

GhWorkflowEntry

interface

interface GhWorkflowEntry

One workflow of "./gh.ts".GhTasks.workflowListEntries.

Member	Signature	Doc
`id?`	`id?: number`	The workflow's numeric id.
`name?`	`name?: string`	Its name, as the `name:` key of its file declares it.
`path?`	`path?: string`	Its path in the repository, e.g. `.github/workflows/ci.yml`.
`state?`	`state?: string`	Its state, as gh reports it: `active`, `disabled_manually`, …

GhWorkflowListSettings

class

class GhWorkflowListSettings extends GhReadSettings

Settings for gh workflow list.

Member	Signature	Doc
`all`	`all(): this`	Include disabled workflows (`--all`).
`limit`	`limit(count: number): this`	Cap how many are fetched (`--limit`); gh's default is 50.

GhWorkflowRunSettings

class

class GhWorkflowRunSettings extends GhWorkflowTargetSettings

Settings for gh workflow run — dispatching a workflow_dispatch run.

Member	Signature	Doc
`ref`	`ref(name: string): this`	The branch or tag to run it on (`--ref`).
`field`	`field(key: string, value: string \| number \| boolean): this`	An input, as `--field key=value`. gh reads a leading `@` in the value as a file to read, so use `rawField` for a value that starts with one.
`rawField`	`rawField(key: string, value: string \| number \| boolean): this`	An input passed verbatim (`--raw-field`), with no `@` file syntax.
`jsonInput`	`jsonInput(): this`	Read the whole input object as JSON on standard input (`--json`).

GhWorkflowTargetSettings

class

class GhWorkflowTargetSettings extends GhCommandSettings

Base for the workflow commands that name one workflow, which gh takes by file name, name, or numeric id.

Member	Signature	Doc
`workflow`	`workflow(nameOrId: string \| number): this`	The workflow — its file name, its name, or its id (required).

GhWorkflowViewSettings

class

class GhWorkflowViewSettings extends GhWorkflowTargetSettings

Settings for gh workflow view.

Unlike the other viewing commands this one prints no JSON — gh gives it --yaml and --web but no --json — so it does not carry the read flags.

Member	Signature	Doc
`ref`	`ref(name: string): this`	The branch or tag holding the version to view (`--ref`).
`yaml`	`yaml(): this`	Print the workflow's YAML rather than its summary (`--yaml`).
`web`	`web(): this`	Open it in a browser instead of printing it (`--web`). A build has no browser, so this is for a developer running the target by hand.

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

ISSUE_LIST_FIELDS

const

const ISSUE_LIST_FIELDS: unknown

The --json fields readIssues asks for; gh requires the list by name, so the reader pins the set GhIssueEntry describes.

LABEL_LIST_FIELDS

const

const LABEL_LIST_FIELDS: unknown

The --json fields readLabels asks for; gh requires the list by name, so the reader pins the set GhLabelEntry describes.

markReleaseLatest

function

async function markReleaseLatest(configure?: Configure<GhReleaseLatestSettings>): Promise<GhReleaseLatestResult>

Perform the configured mark-latest call.

mintAppToken

function

async function mintAppToken(configure?: Configure<GhAppTokenSettings>): Promise<GhAppTokenResult>

Mint an installation token from the settings a lambda configures.

openPullRequest

function

async function openPullRequest(configure?: unknown): Promise<GhPullRequestResult>

Perform the configured pull request.

postCheckRun

function

async function postCheckRun(configure?: unknown): Promise<GhCheckRunResult>

Perform the configured check run.

PR_LIST_FIELDS

const

const PR_LIST_FIELDS: unknown

The --json fields readPullRequests asks for. gh requires the list by name — there is no "everything" form — so the reader pins the set its GhPullRequestEntry describes.

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>")).

RELEASE_LIST_FIELDS

const

const RELEASE_LIST_FIELDS: unknown

The --json fields readReleases asks for; gh requires the list by name, so the reader pins the set GhReleaseEntry describes.

REPO_LIST_FIELDS

const

const REPO_LIST_FIELDS: unknown

The --json fields readRepositories asks for; gh requires the list by name, so the reader pins the set GhRepositoryEntry describes.

RUN_LIST_FIELDS

const

const RUN_LIST_FIELDS: unknown

The --json fields readRuns asks for; gh requires the list by name, so the reader pins the set GhRunEntry describes.

SECRET_LIST_FIELDS

const

const SECRET_LIST_FIELDS: unknown

The --json fields readSecrets asks for; gh requires the list by name, so the reader pins the set GhSecretEntry describes.

tagCommit

function

async function tagCommit(configure?: unknown): Promise<void>

Perform the configured tag.

uploadReleaseAsset

function

async function uploadReleaseAsset(configure?: Configure<GhReleaseAssetSettings>): Promise<GhReleaseAssetResult>

Upload the release asset the settings describe.

uploadSarifReport

function

async function uploadSarifReport(configure?: Configure<GhSarifSettings>): Promise<GhSarifUploadResult>

Upload the SARIF report the settings describe.

VARIABLE_LIST_FIELDS

const

const VARIABLE_LIST_FIELDS: unknown

The --json fields readVariables asks for; gh requires the list by name, so the reader pins the set GhVariableEntry describes.

WORKFLOW_LIST_FIELDS

const

const WORKFLOW_LIST_FIELDS: unknown

The --json fields readWorkflows asks for; gh requires the list by name, so the reader pins the set GhWorkflowEntry describes.

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.