zuke.tools.gh

class GhApiSettings(ToolSettings)

• method(verb: str) -> Self

  The HTTP method (--method, e.g. "PUT"; gh defaults to GET).

• field(key: str, value: str | float | bool) -> Self

  Add a typed body parameter (--field key=value). Repeatable.

• raw_field(key: str, value: str) -> Self

  Add a string body parameter (--raw-field key=value). Repeatable.

• header(name: str, value: str) -> Self

  Add a request header (--header key:value). Repeatable.

• jq(expression: str) -> Self

  Filter the response through a jq expression (--jq).

• silent() -> Self

  Do not print the response body (--silent).

class GhAppTokenSettings(Settings)

• app_id(id: str | float) -> Self

  The GitHub App's id (the App ID on its settings page).

• private_key(pem: str) -> Self

  The app's private key, as the PEM's contents — GitHub issues PKCS#1 (BEGIN RSA PRIVATE KEY); PKCS#8 is accepted too.

• owner(login: str) -> Self

  The user or organisation the app is installed on.

• repositories(*names: str) -> Self

  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(name: str, level: Literal['read', 'write', 'admin']) -> Self

  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.

• base_url(url: str) -> Self

  Use a different REST base (GitHub Enterprise Server).

class GhAppTokenSourceSettings(Settings)

• app(app_id: str, private_key: str) -> Self

  The App's credentials — its numeric id and the PEM contents of its private key, as the build's parameters (.secret() for the key). Either one unset at call time means "no App": the source yields the fallback. Both are read when the token is first needed, never at construction, so parameters declared on the build resolve first.

• repository(slug: str) -> Self

  The repository to mint for, as owner/name. Defaults to the repository the run is on, GITHUB_REPOSITORY. Name it to refuse minting anywhere else: a run whose GITHUB_REPOSITORY is another repository then gets the fallback, with a warning, rather than a token for this one minted into a build running elsewhere.

• permission(name: str, level: Literal['read', 'write', 'admin']) -> Self

  Narrow the token to one permission, e.g. .permission("contents", "write"). Repeatable. Without any, the token holds the installation's whole grant, which is the App's configured permissions — the sane default for an App set up for one job. A hyphenated name is accepted as the mint accepts it.

• fallback(token: str) -> Self

  The token yielded when no App is configured or the mint fails. Defaults to GITHUB_TOKEN from the environment — the workflow's own token, so a build that names an App still posts, as github-actions[bot], wherever the App is absent.

• base_url(url: str) -> Self

  Use a different REST base for the mint (GitHub Enterprise Server).

class GhBodySettings(GhCommandSettings)

• body(text: str) -> Self

  The message text (--body).

• body_file(path: str) -> Self

  Read the message from a file (--body-file); - reads standard input.

class GhCacheDeleteSettings(GhCommandSettings)

• selector(id_or_key: str | float) -> Self

  The cache to delete, by its id or its key.

• all() -> Self

  Delete every cache (--all), narrowed by ref when one is set.

• ref(name: str) -> Self

  Restrict the deletion to one ref (--ref).

• succeed_on_no_caches() -> Self

  Exit zero when there was nothing to delete (--succeed-on-no-caches).

class GhCacheListSettings(GhReadSettings)

• key(prefix: str) -> Self

  Only caches whose key starts with this (--key).

• ref(name: str) -> Self

  Only caches for this ref (--ref), e.g. refs/heads/master.

• sort(field: Literal['created_at', 'last_accessed_at', 'size_in_bytes']) -> Self

  What to order by (--sort); gh's default is last_accessed_at.

• order(direction: Literal['asc', 'desc']) -> Self

  The direction (--order): asc or desc.

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

class GhCommandSettings(GhSettings)

class GhContentsSettings(Settings)

• path(value: str) -> Self

  The file's path inside the repository, e.g. Formula/app.rb (required). Relative, /-separated, with no . or .. segment.

• content(text: str) -> Self

  The file's new content, as text (required). Written as UTF-8.

• message(text: str) -> Self

  The commit message (required).

• branch(name: str) -> Self

  The branch to write on. Defaults to the repository's default branch.

• repo(slug: str) -> Self

  owner/repo. Defaults to GITHUB_REPOSITORY.

• token(value: str) -> Self

  The token to authenticate with — needs contents: write on the repository. Defaults to GITHUB_TOKEN.

• base_url(url: str) -> Self

  The API root, for GitHub Enterprise.

class GhIssueCloseSettings(GhCommandSettings)

• selector(value: str | float) -> Self

  The issue — its number or URL (required).

• comment(text: str) -> Self

  Leave a closing comment (--comment).

• reason(value: Literal['completed', 'not planned', 'duplicate']) -> Self

  Why it is closed (--reason).

• duplicate_of(number_or_url: str | float) -> Self

  Which issue it duplicates (--duplicate-of), by number or URL.

class GhIssueCommentSettings(GhBodySettings)

• selector(value: str | float) -> Self

  The issue — its number or URL (required).

• edit_last() -> Self

  Edit your most recent comment instead of adding one (--edit-last).

• create_if_none() -> Self

  With editLast, post a new comment when there is none (--create-if-none).

• delete_last() -> Self

  Delete your most recent comment (--delete-last).

• yes() -> Self

  Skip the confirmation a delete otherwise prompts for (--yes).

class GhIssueCreateSettings(GhBodySettings)

• title(text: str) -> Self

  The issue's title (--title).

• assignee(*logins: str) -> Self

  Assign someone by login (--assignee), @me for yourself; repeatable.

• label(*names: str) -> Self

  Add a label by name (--label); repeatable.

• project(*titles: str) -> Self

  Add to a project by title (--project); repeatable.

• milestone(name: str) -> Self

  Add to a milestone by name (--milestone).

• type_(name: str) -> Self

  Set the issue type by name (--type).

• parent(number_or_url: str | float) -> Self

  File it as a sub-issue of this number or URL (--parent).

• template_name(name: str) -> Self

  The issue template to start the body from (--template).

class GhIssueListSettings(GhWebReadSettings)

• state(value: Literal['open', 'closed', 'all']) -> Self

  Filter by state (--state): open, closed, or all.

• author(login: str) -> Self

  Filter by author (--author).

• app(name: str) -> Self

  Filter by the GitHub App that opened it (--app).

• assignee(login: str) -> Self

  Filter by assignee (--assignee).

• mention(login: str) -> Self

  Filter by who is mentioned (--mention).

• milestone(name_or_number: str) -> Self

  Filter by milestone number or title (--milestone).

• type_(name: str) -> Self

  Filter by issue type (--type).

• label(*names: str) -> Self

  Filter by label (--label); repeatable.

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

• search(query: str) -> Self

  Filter with a search query (--search).

class GhIssueViewSettings(GhWebReadSettings)

• selector(value: str | float) -> Self

  The issue — its number or URL (required).

• comments() -> Self

  Include the comments (--comments).

class GhLabelCloneSettings(GhCommandSettings)

• source(slug: str) -> Self

  The repository to copy the labels from, as owner/name (required).

• force() -> Self

  Overwrite labels of the same name in the destination (--force).

class GhLabelCreateSettings(GhCommandSettings)

• name(value: str) -> Self

  The label's name (required).

• color(hex: str) -> Self

  Its colour (--color), as a hex triplet; gh accepts it with or without #.

• description(text: str) -> Self

  Its description (--description).

• force() -> Self

  Update the label when it already exists rather than failing (--force).

class GhLabelDeleteSettings(GhCommandSettings)

• name(value: str) -> Self

  The label to delete (required).

• yes() -> Self

  Skip the confirmation a delete otherwise prompts for (--yes).

class GhLabelEditSettings(GhCommandSettings)

• name(value: str) -> Self

  The label to edit, by its current name (required).

• new_name(value: str) -> Self

  Rename it (--name).

• color(hex: str) -> Self

  Set its colour (--color).

• description(text: str) -> Self

  Set its description (--description).

class GhLabelListSettings(GhWebReadSettings)

• search(query: str) -> Self

  Search names and descriptions (--search).

• sort(field: Literal['created', 'name']) -> Self

  What to order by (--sort); gh's default is created.

• order(direction: Literal['asc', 'desc']) -> Self

  The direction (--order): asc or desc.

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

class GhPrChecksSettings(GhPrReadSettings)

• watch() -> Self

  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.

• fail_fast() -> Self

  Stop watching at the first failure (--fail-fast).

• required() -> Self

  Only the checks marked required (--required).

• interval(seconds: float) -> Self

  How often to refresh while watching (--interval), in seconds.

class GhPrCloseSettings(GhCommandSettings)

• selector(value: str | float) -> Self

  The pull request — number, URL, or branch; defaults to the current branch's.

• comment(text: str) -> Self

  Leave a closing comment (--comment).

• delete_branch() -> Self

  Delete the branch afterwards (--delete-branch).

class GhPrCommentSettings(GhPrTargetSettings)

• edit_last() -> Self

  Edit your most recent comment instead of adding one (--edit-last).

• create_if_none() -> Self

  With editLast, post a new comment when there is none (--create-if-none).

• delete_last() -> Self

  Delete your most recent comment (--delete-last).

• yes() -> Self

  Skip the confirmation a delete otherwise prompts for (--yes).

class GhPrCreateSettings(GhBodySettings)

• title(text: str) -> Self

  The pull request's title (--title).

• base(branch: str) -> Self

  The branch to merge into (--base).

• head(branch: str) -> Self

  The branch holding the commits (--head).

• assignee(*logins: str) -> Self

  Assign someone by login (--assignee), @me for yourself; repeatable.

• label(*names: str) -> Self

  Add a label by name (--label); repeatable.

• reviewer(*handles: str) -> Self

  Request a review from a person or team (--reviewer); repeatable.

• milestone(name: str) -> Self

  Add to a milestone by name (--milestone).

• project(*titles: str) -> Self

  Add to a project by title (--project); repeatable.

• draft() -> Self

  Open it as a draft (--draft).

• fill() -> Self

  Take the title and body from the commits (--fill).

• fill_first() -> Self

  Take them from the first commit only (--fill-first).

• fill_verbose() -> Self

  Take the body from every commit's message (--fill-verbose).

• dry_run() -> Self

  Print what would be created without creating it (--dry-run).

• no_maintainer_edit() -> Self

  Refuse maintainer edits to the branch (--no-maintainer-edit).

• template_file(path: str) -> Self

  A template file to seed the body from (--template).

class GhPrEditSettings(GhPrTargetSettings)

• title(text: str) -> Self

  Set the title (--title).

• base(branch: str) -> Self

  Change the base branch (--base).

• add_label(*names: str) -> Self

  Add a label (--add-label); repeatable.

• remove_label(*names: str) -> Self

  Remove a label (--remove-label); repeatable.

• add_assignee(*logins: str) -> Self

  Add an assignee (--add-assignee); repeatable.

• remove_assignee(*logins: str) -> Self

  Remove an assignee (--remove-assignee); repeatable.

• add_reviewer(*handles: str) -> Self

  Request a review (--add-reviewer); repeatable.

• remove_reviewer(*handles: str) -> Self

  Drop a review request (--remove-reviewer); repeatable.

• add_project(*titles: str) -> Self

  Add to a project by title (--add-project); repeatable.

• remove_project(*titles: str) -> Self

  Take it off a project by title (--remove-project); repeatable.

• milestone(name: str) -> Self

  Set the milestone (--milestone).

• remove_milestone() -> Self

  Clear the milestone (--remove-milestone).

class GhPrListSettings(GhWebReadSettings)

• state(value: Literal['open', 'closed', 'merged', 'all']) -> Self

  Filter by state (--state): open, closed, merged, or all.

• base(branch: str) -> Self

  Filter by base branch (--base).

• head(branch: str) -> Self

  Filter by head branch (--head).

• author(login: str) -> Self

  Filter by author (--author).

• app(name: str) -> Self

  Filter by the GitHub App that opened it (--app).

• assignee(login: str) -> Self

  Filter by assignee (--assignee).

• label(*names: str) -> Self

  Filter by label (--label); repeatable.

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

• search(query: str) -> Self

  Filter with a search query (--search).

• draft() -> Self

  Only draft pull requests (--draft).

class GhPrMergeSettings(GhPrTargetSettings)

• merge() -> Self

  Merge with a merge commit (--merge).

• squash() -> Self

  Squash the commits into one (--squash).

• rebase() -> Self

  Rebase the commits onto the base (--rebase).

• auto() -> Self

  Merge once the requirements are met (--auto).

• disable_auto() -> Self

  Turn auto-merge off again (--disable-auto).

• admin() -> Self

  Merge with administrator privileges (--admin).

• delete_branch() -> Self

  Delete the branch afterwards (--delete-branch).

• subject(text: str) -> Self

  The merge commit's subject (--subject).

• author_email(address: str) -> Self

  The merge commit's author email (--author-email).

• match_head_commit(sha: str) -> Self

  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.

class GhPrReadSettings(GhWebReadSettings)

• selector(value: str | float) -> Self

  The pull request — number, URL, or branch; defaults to the current branch's.

class GhPrTargetSettings(GhBodySettings)

• selector(value: str | float) -> Self

  The pull request — its number, URL, or branch name. Omit it to act on the PR for the current branch, as gh does.

class GhPrViewSettings(GhPrReadSettings)

• comments() -> Self

  Include the comments (--comments).

class GhReadSettings(GhCommandSettings)

• json(*fields: str) -> Self

  Emit JSON with these fields (--json), which gh requires by name — there is no "all fields" form.

• jq(expression: str) -> Self

  Filter the JSON with a jq expression (--jq).

• template(text: str) -> Self

  Format the JSON through a Go template (--template).

class GhReleaseAssetSettings(Settings)

• file(path: str) -> Self

  The file to upload (required).

• name(value: str) -> Self

  The asset's name on the release. Defaults to the file's base name.

• content_type(value: str) -> Self

  The asset's content-type. Defaults by extension (.tar.gz/.tgz, .zip, .json), then to application/octet-stream.

• repo(slug: str) -> Self

  The owner/repo to upload to. Defaults to GITHUB_REPOSITORY.

• tag(value: str) -> Self

  Attach to the release with this tag instead of the latest release.

• refresh() -> Self

  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(value: str) -> Self

  The token to authenticate with — needs contents: write. Defaults to GITHUB_TOKEN in the environment, so it never has to reach argv.

• base_url(url: str) -> Self

  Use a different REST base (GitHub Enterprise Server).

class GhReleaseCreateSettings(GhCommandSettings)

• tag(name: str) -> Self

  The tag to release (required); gh creates it when it does not exist.

• files(*paths: str) -> Self

  Asset files to attach (positional); repeatable. gh reads a #label suffix on a path as the asset's display label.

• title(text: str) -> Self

  The release title (--title).

• notes(text: str) -> Self

  The release notes (--notes).

• notes_file(path: str) -> Self

  Read the notes from a file (--notes-file); - reads standard input.

• generate_notes() -> Self

  Have GitHub write the title and notes (--generate-notes).

• notes_from_tag() -> Self

  Take the notes from the tag's annotation (--notes-from-tag).

• notes_start_tag(name: str) -> Self

  Generate notes starting from this tag (--notes-start-tag).

• draft() -> Self

  Save it as a draft rather than publishing (--draft).

• prerelease() -> Self

  Mark it a prerelease (--prerelease).

• latest() -> Self

  Mark it the latest release (--latest).

• target(branch_or_sha: str) -> Self

  The branch or commit to tag (--target).

• discussion_category(name: str) -> Self

  Open a discussion in this category (--discussion-category).

• verify_tag() -> Self

  Abort unless the tag already exists on the remote (--verify-tag).

• fail_on_no_commits() -> Self

  Fail when there are no commits since the last release (--fail-on-no-commits).

class GhReleaseDeleteSettings(GhCommandSettings)

• tag(name: str) -> Self

  The release to delete, by tag (required).

• cleanup_tag() -> Self

  Delete the git tag as well (--cleanup-tag).

• yes() -> Self

  Skip the confirmation prompt (--yes).

class GhReleaseDownloadSettings(GhCommandSettings)

• tag(name: str) -> Self

  The release's tag; gh takes the latest release when it is omitted.

• pattern(*globs: str) -> Self

  Only assets matching this glob (--pattern); repeatable.

• dir(path: str) -> Self

  The directory to download into (--dir).

• output(path: str) -> Self

  Write a single asset to this file (--output); - writes standard output.

• archive(format: Literal['zip', 'tar.gz']) -> Self

  Download the source archive instead of the assets (--archive).

• clobber() -> Self

  Overwrite files that already exist (--clobber).

• skip_existing() -> Self

  Leave files that already exist alone (--skip-existing).

class GhReleaseEditSettings(GhCommandSettings)

• tag(name: str) -> Self

  The release to edit, by its current tag (required).

• new_tag(name: str) -> Self

  Move the release to a different tag (--tag).

• title(text: str) -> Self

  Set the title (--title).

• notes(text: str) -> Self

  Set the notes (--notes).

• notes_file(path: str) -> Self

  Read the notes from a file (--notes-file); - reads standard input.

• draft() -> Self

  Make it a draft (--draft).

• prerelease() -> Self

  Mark it a prerelease (--prerelease).

• latest() -> Self

  Mark it the latest release (--latest).

• target(branch_or_sha: str) -> Self

  Change the target branch or commit (--target).

• discussion_category(name: str) -> Self

  Open a discussion in this category when publishing (--discussion-category).

• verify_tag() -> Self

  Abort unless the tag exists on the remote (--verify-tag).

class GhReleaseEnsureSettings(Settings)

• tag(value: str) -> Self

  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(text: str) -> Self

  The release title (required), e.g. Zuke Build v1.2.3.

• body(text: str) -> Self

  The release notes (required); pass "" for a release with none.

• latest(value: bool | None=None) -> Self

  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(slug: str) -> Self

  owner/repo. Defaults to GITHUB_REPOSITORY.

• token(value: str) -> Self

  The token to authenticate with — needs contents: write. Defaults to GITHUB_TOKEN.

• base_url(url: str) -> Self

  The API root, for GitHub Enterprise.

class GhReleaseLatestSettings(Settings)

• tag(value: str) -> Self

  The tag whose release the pointer should name (required).

• repo(slug: str) -> Self

  owner/repo. Defaults to GITHUB_REPOSITORY.

• token(value: str) -> Self

  The token to authenticate with — needs contents: write. Defaults to GITHUB_TOKEN.

• base_url(url: str) -> Self

  The API root, for GitHub Enterprise.

class GhReleaseListSettings(GhReadSettings)

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

• order(direction: Literal['asc', 'desc']) -> Self

  The order they come back in (--order): asc or desc.

• exclude_drafts() -> Self

  Leave out drafts (--exclude-drafts).

• exclude_pre_releases() -> Self

  Leave out prereleases (--exclude-pre-releases).

class GhReleaseUploadSettings(GhCommandSettings)

• tag(name: str) -> Self

  The release's tag (required).

• files(*paths: str) -> Self

  Asset files to attach (required); repeatable. gh reads a #label suffix on a path as the asset's display label.

• clobber() -> Self

  Replace an asset of the same name (--clobber).

class GhReleaseViewSettings(GhWebReadSettings)

• tag(name: str) -> Self

  The release's tag; gh shows the latest release when it is omitted.

class GhRepoArchiveSettings(GhRepoCommandSettings)

• repository(slug: str) -> Self

  The repository; gh acts on the current one otherwise.

• unarchive() -> Self

  Restore an archived repository instead — gh repo unarchive.

• yes() -> Self

  Skip the confirmation gh otherwise prompts for (--yes).

class GhRepoCloneSettings(GhRepoCommandSettings)

• repository(slug: str) -> Self

  The repository, as owner/name or a URL (required).

• directory(path: str) -> Self

  The directory to clone into; gh names it after the repository otherwise.

• upstream_remote_name(name: str) -> Self

  The remote name for a fork's parent (--upstream-remote-name).

• no_upstream() -> Self

  Do not add the upstream remote when cloning a fork (--no-upstream).

• git_args(*args: str) -> Self

  Flags for the underlying git clone, which gh takes after a -- separator — .gitArgs("--depth=1") for a shallow clone.

class GhRepoCommandSettings(GhCommandSettings)

class GhRepoCreateSettings(GhRepoCommandSettings)

• name(value: str) -> Self

  The repository's name, or owner/name to create it elsewhere (required).

• visibility(value: Literal['public', 'private', 'internal']) -> Self

  How visible it is: --public, --private, or --internal (required).

• description(text: str) -> Self

  Its description (--description).

• homepage(url: str) -> Self

  Its homepage (--homepage).

• team(name: str) -> Self

  Grant an organization team access (--team).

• template(slug: str) -> Self

  Base it on a template repository (--template).

• gitignore(name: str) -> Self

  Start from a gitignore template (--gitignore).

• license(name: str) -> Self

  Add an open-source license (--license).

• source(path: str) -> Self

  Create it from a local repository (--source).

• remote(name: str) -> Self

  The remote name for the new repository (--remote).

• clone() -> Self

  Clone it after creating it (--clone).

• push() -> Self

  Push the local commits to it (--push).

• add_readme() -> Self

  Add a README (--add-readme).

• include_all_branches() -> Self

  Copy every branch of the template, not just its default (--include-all-branches).

• disable_issues() -> Self

  Turn issues off (--disable-issues).

• disable_wiki() -> Self

  Turn the wiki off (--disable-wiki).

class GhRepoDeleteSettings(GhRepoCommandSettings)

• repository(slug: str) -> Self

  The repository to delete, as owner/name (required — see below).

• yes() -> Self

  Skip the confirmation a delete otherwise prompts for (--yes).

class GhRepoEditSettings(GhRepoCommandSettings)

• repository(slug: str) -> Self

  The repository to edit; gh edits the current one otherwise.

• description(text: str) -> Self

  Set the description (--description).

• homepage(url: str) -> Self

  Set the homepage (--homepage).

• default_branch(name: str) -> Self

  Set the default branch (--default-branch).

• visibility(value: Literal['public', 'private', 'internal']) -> Self

  Change the visibility (--visibility), which needs acceptVisibilityChangeConsequences.

• accept_visibility_change_consequences() -> Self

  Acknowledge what a visibility change does (--accept-visibility-change-consequences).

• add_topic(*names: str) -> Self

  Add a topic (--add-topic); repeatable.

• remove_topic(*names: str) -> Self

  Remove a topic (--remove-topic); repeatable.

• enable_issues(enabled: bool | None=None) -> Self

  Turn issues on or off (--enable-issues).

• enable_wiki(enabled: bool | None=None) -> Self

  Turn the wiki on or off (--enable-wiki).

• enable_projects(enabled: bool | None=None) -> Self

  Turn projects on or off (--enable-projects).

• enable_discussions(enabled: bool | None=None) -> Self

  Turn discussions on or off (--enable-discussions).

• enable_auto_merge(enabled: bool | None=None) -> Self

  Turn auto-merge on or off (--enable-auto-merge).

• enable_merge_commit(enabled: bool | None=None) -> Self

  Allow or forbid merge commits (--enable-merge-commit).

• enable_squash_merge(enabled: bool | None=None) -> Self

  Allow or forbid squash merges (--enable-squash-merge).

• enable_rebase_merge(enabled: bool | None=None) -> Self

  Allow or forbid rebase merges (--enable-rebase-merge).

• delete_branch_on_merge(enabled: bool | None=None) -> Self

  Delete the head branch after a merge, or stop (--delete-branch-on-merge).

• allow_forking(enabled: bool | None=None) -> Self

  Allow or forbid forking (--allow-forking).

• allow_update_branch(enabled: bool | None=None) -> Self

  Allow or forbid updating a pull request branch (--allow-update-branch).

• enable_secret_scanning(enabled: bool | None=None) -> Self

  Turn secret scanning on or off (--enable-secret-scanning).

• enable_secret_scanning_push_protection(enabled: bool | None=None) -> Self

  Turn push protection on or off (--enable-secret-scanning-push-protection).

class GhRepoForkSettings(GhRepoCommandSettings)

• repository(slug: str) -> Self

  The repository to fork; gh forks the current one otherwise.

• org(name: str) -> Self

  Create the fork in an organization (--org).

• fork_name(value: str) -> Self

  Name the fork something else (--fork-name).

• remote_name(value: str) -> Self

  The remote name to add for the fork (--remote-name).

• clone() -> Self

  Clone the fork after creating it (--clone).

• remote() -> Self

  Add a git remote for the fork (--remote).

• default_branch_only() -> Self

  Fork only the default branch (--default-branch-only).

• git_args(*args: str) -> Self

  Flags for the underlying git clone, passed after a -- separator.

class GhRepoListSettings(GhReadSettings)

• owner(login: str) -> Self

  Whose repositories to list; gh lists your own when it is omitted.

• language(name: str) -> Self

  Filter by primary language (--language).

• topic(*names: str) -> Self

  Filter by topic (--topic); repeatable.

• visibility(value: Literal['public', 'private', 'internal']) -> Self

  Filter by visibility (--visibility).

• archived() -> Self

  Only archived repositories (--archived).

• no_archived() -> Self

  Leave archived repositories out (--no-archived).

• fork() -> Self

  Only forks (--fork).

• source() -> Self

  Only repositories that are not forks (--source).

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 30.

class GhRepoRenameSettings(GhCommandSettings)

• new_name(value: str) -> Self

  The repository's new name, without the owner (required).

• yes() -> Self

  Skip the confirmation a rename otherwise prompts for (--yes).

class GhRepoSetDefaultSettings(GhRepoCommandSettings)

• repository(slug_or_remote: str) -> Self

  The repository to make the default, as owner/name or a remote name.

• unset() -> Self

  Forget the current default instead (--unset).

• view() -> Self

  Report the current default instead (--view).

class GhRepoSyncSettings(GhRepoCommandSettings)

• destination(slug: str) -> Self

  The repository to update; gh syncs the local one otherwise.

• source(slug: str) -> Self

  Where to sync from (--source); gh uses the fork's parent otherwise.

• branch(name: str) -> Self

  The branch to sync (--branch); gh uses the default branch otherwise.

• force() -> Self

  Hard-reset the destination branch onto the source (--force).

class GhRepoViewSettings(GhWebReadSettings)

• repository(slug: str) -> Self

  The repository, as owner/name; gh uses the current one otherwise.

• branch(name: str) -> Self

  View a particular branch (--branch).

class GhRunCancelSettings(GhRunTargetSettings)

• force() -> Self

  Cancel a run the ordinary request will not stop (--force).

class GhRunDeleteSettings(GhRunTargetSettings)

class GhRunDownloadSettings(GhRunTargetSettings)

• name(*names: str) -> Self

  Only artifacts with this exact name (--name); repeatable.

• pattern(*globs: str) -> Self

  Only artifacts matching this glob (--pattern); repeatable.

• dir(path: str) -> Self

  The directory to download into (--dir); gh's default is the cwd.

class GhRunListSettings(GhReadSettings)

• all() -> Self

  Include runs of disabled workflows (--all).

• branch(name: str) -> Self

  Filter by branch (--branch).

• commit(sha: str) -> Self

  Filter by the commit that triggered them (--commit).

• created(query: str) -> Self

  Filter by creation date (--created), in GitHub's date-query syntax.

• event(name: str) -> Self

  Filter by the event that triggered them (--event).

• status(value: Literal['queued', 'completed', 'in_progress', 'requested', 'waiting', 'pending', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'startup_failure', 'success', 'timed_out']) -> Self

  Filter by status or conclusion (--status).

• user(login: str) -> Self

  Filter by the user who triggered them (--user).

• workflow(name_or_id: str) -> Self

  Filter by workflow, by name, id, or file name (--workflow).

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 20.

class GhRunRerunSettings(GhRunTargetSettings)

• failed() -> Self

  Rerun only the failed jobs and their dependencies (--failed).

• job(job_id: str | float) -> Self

  Rerun one job and its dependencies (--job), by job id.

• debug() -> Self

  Rerun with debug logging enabled (--debug).

class GhRunTargetSettings(GhCommandSettings)

• selector(run_id: str | float) -> Self

  The run — its id (required).

class GhRunViewSettings(GhWebReadSettings)

• selector(run_id: str | float) -> Self

  The run — its id; gh shows a picker without one.

• attempt(number: float) -> Self

  View an earlier attempt (--attempt).

• job(job_id: str | float) -> Self

  View one job of the run (--job), by job id.

• log() -> Self

  Print the full log (--log).

• log_failed() -> Self

  Print only the failed steps' log (--log-failed).

• exit_status() -> Self

  Exit non-zero when the run failed (--exit-status).

• verbose() -> Self

  Include the individual job steps (--verbose).

class GhRunWatchSettings(GhRunTargetSettings)

• compact() -> Self

  Report only the relevant and failed steps (--compact).

• exit_status() -> Self

  Exit non-zero when the run fails (--exit-status).

• interval(seconds: float) -> Self

  Seconds between refreshes (--interval); gh's default is 3.

class GhSarifSettings(Settings)

• file(path: str) -> Self

  The SARIF report to upload (required).

• repo(slug: str) -> Self

  The owner/repo to upload for. Defaults to GITHUB_REPOSITORY.

• commit(sha: str) -> Self

  The commit SHA the results describe. Defaults to GITHUB_SHA.

• ref(ref: str) -> Self

  The full ref the results describe (refs/heads/main). Defaults to GITHUB_REF.

• token(value: str) -> Self

  The token to authenticate with — needs security-events: write. Defaults to GITHUB_TOKEN in the environment, so it never has to reach argv.

• checkout_uri(uri: str) -> Self

  The URI of the checkout the results are relative to (file:///…).

• base_url(url: str) -> Self

  Use a different REST base (GitHub Enterprise Server).

class GhSecretDeleteSettings(GhSecretScopeSettings)

• name(value: str) -> Self

  The secret's name (required).

class GhSecretListSettings(GhReadSettings)

• app(name: Literal['actions', 'agents', 'codespaces', 'dependabot']) -> Self

  Which application's secrets to list (--app).

• org(name: str) -> Self

  List an organization's secrets (--org).

• environment(name: str) -> Self

  List an environment's secrets (--env).

• user() -> Self

  List your own secrets (--user).

class GhSecretScopeSettings(GhCommandSettings)

• app(name: Literal['actions', 'agents', 'codespaces', 'dependabot']) -> Self

  Which application reads it (--app); gh's default is actions.

• org(name: str) -> Self

  Scope it to an organization (--org).

• environment(name: str) -> Self

  Scope it to a deployment environment (--env).

• user() -> Self

  Scope it to the authenticated user (--user).

• repositories(*names: str) -> Self

  Share an organization secret with these repositories (--repos).

• visibility(value: Literal['all', 'private', 'selected']) -> Self

  The visibility of an organization secret (--visibility).

class GhSecretSetSettings(GhSecretScopeSettings)

• name(value: str) -> Self

  The secret's name (required).

• body(value: str) -> Self

  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.

• env_file(path: str) -> Self

  Read names and values from a dotenv file (--env-file).

• no_store() -> Self

  Print the encrypted value instead of storing it (--no-store).

• no_repos_selected() -> Self

  Share the organization secret with no repositories (--no-repos-selected).

class GhSettings(SubcommandSettings)

• repo(slug: str) -> Self

  Target repository as OWNER/REPO (-R/--repo).

class GhTasks

• static async app_token(ctx: ServiceContext, configure: Callable[[GhAppTokenSettings], GhAppTokenSettings] | None=None) -> object

  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.

• static async app_token_source(ctx: ServiceContext, configure: Callable[[GhAppTokenSourceSettings], GhAppTokenSourceSettings] | None=None) -> object

  A token source for the App: a function that mints the installation token the first time it is called and returns the same token after, or yields GITHUB_TOKEN when the App is not configured — the credential a build hands to an AI reviewer's .commentToken(...) so its reviews post as the App where it is installed and as github-actions[bot] everywhere else. Nothing runs until the first call. `ts appId = parameter("GitHub App id").env("REVIEW_APP_ID"); appKey = parameter("GitHub App key").secret().env("REVIEW_APP_KEY"); botToken = GhTasks.appTokenSource((s) => s.app(this.appId, this.appKey)); `

• static async upload_sarif(ctx: ServiceContext, configure: Callable[[GhSarifSettings], GhSarifSettings] | None=None) -> object

  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.

• static async upload_release_asset(ctx: ServiceContext, configure: Callable[[GhReleaseAssetSettings], GhReleaseAssetSettings] | None=None) -> object

  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.

• static async mark_release_latest(ctx: ServiceContext, configure: Callable[[GhReleaseLatestSettings], GhReleaseLatestSettings] | None=None) -> object

  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.

• static async ensure_release(ctx: ServiceContext, configure: Callable[[GhReleaseEnsureSettings], GhReleaseEnsureSettings] | None=None) -> object

  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.

• static async create_or_update_file(ctx: ServiceContext, configure: Callable[[GhContentsSettings], GhContentsSettings] | None=None) -> object

  Write one file through the contents API, creating it or replacing its content — or, when it already holds exactly this content, writing nothing and reporting unchanged. A write that loses a race (the file changed between the read and the write) is read once more: if the file now holds this content the result is unchanged, otherwise the conflict is raised rather than overwritten.

• static async pr_create(ctx: ServiceContext, configure: Callable[[GhPrCreateSettings], GhPrCreateSettings] | None=None) -> ExecResult

  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.

• static async pr_list(ctx: ServiceContext, configure: Callable[[GhPrListSettings], GhPrListSettings] | None=None) -> ExecResult

  List pull requests: gh pr list.

• static async pr_list_entries(ctx: ServiceContext, configure: Callable[[GhPrListSettings], GhPrListSettings] | None=None) -> object

  The pull requests as parsed GhPullRequestEntry values. The --json field set is pinned, since gh requires one by name.

• static async pr_view(ctx: ServiceContext, configure: Callable[[GhPrViewSettings], GhPrViewSettings] | None=None) -> ExecResult

  Show a pull request: gh pr view.

• static async pr_checks(ctx: ServiceContext, configure: Callable[[GhPrChecksSettings], GhPrChecksSettings] | None=None) -> ExecResult

  Report a pull request's checks: gh pr checks.

• static async pr_merge(ctx: ServiceContext, configure: Callable[[GhPrMergeSettings], GhPrMergeSettings] | None=None) -> ExecResult

  Merge a pull request: gh pr merge.

• static async pr_comment(ctx: ServiceContext, configure: Callable[[GhPrCommentSettings], GhPrCommentSettings] | None=None) -> ExecResult

  Comment on a pull request: gh pr comment.

• static async pr_edit(ctx: ServiceContext, configure: Callable[[GhPrEditSettings], GhPrEditSettings] | None=None) -> ExecResult

  Change a pull request's metadata: gh pr edit.

• static async pr_close(ctx: ServiceContext, configure: Callable[[GhPrCloseSettings], GhPrCloseSettings] | None=None) -> ExecResult

  Close a pull request: gh pr close.

• static async issue_create(ctx: ServiceContext, configure: Callable[[GhIssueCreateSettings], GhIssueCreateSettings] | None=None) -> ExecResult

  Open an issue: gh issue create.

• static async issue_list(ctx: ServiceContext, configure: Callable[[GhIssueListSettings], GhIssueListSettings] | None=None) -> ExecResult

  List issues: gh issue list.

• static async issue_list_entries(ctx: ServiceContext, configure: Callable[[GhIssueListSettings], GhIssueListSettings] | None=None) -> object

  The issues as parsed GhIssueEntry values. The --json field set is pinned, since gh requires one by name.

• static async issue_view(ctx: ServiceContext, configure: Callable[[GhIssueViewSettings], GhIssueViewSettings] | None=None) -> ExecResult

  Show an issue: gh issue view.

• static async issue_comment(ctx: ServiceContext, configure: Callable[[GhIssueCommentSettings], GhIssueCommentSettings] | None=None) -> ExecResult

  Comment on an issue: gh issue comment.

• static async issue_close(ctx: ServiceContext, configure: Callable[[GhIssueCloseSettings], GhIssueCloseSettings] | None=None) -> ExecResult

  Close an issue: gh issue close.

• static async release_create(ctx: ServiceContext, configure: Callable[[GhReleaseCreateSettings], GhReleaseCreateSettings] | None=None) -> ExecResult

  Publish a release: gh release create.

• static async release_list(ctx: ServiceContext, configure: Callable[[GhReleaseListSettings], GhReleaseListSettings] | None=None) -> ExecResult

  List releases: gh release list.

• static async release_list_entries(ctx: ServiceContext, configure: Callable[[GhReleaseListSettings], GhReleaseListSettings] | None=None) -> object

  The releases as parsed GhReleaseEntry values. The --json field set is pinned, since gh requires one by name.

• static async release_view(ctx: ServiceContext, configure: Callable[[GhReleaseViewSettings], GhReleaseViewSettings] | None=None) -> ExecResult

  Show a release: gh release view.

• static async release_upload(ctx: ServiceContext, configure: Callable[[GhReleaseUploadSettings], GhReleaseUploadSettings] | None=None) -> ExecResult

  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.

• static async release_download(ctx: ServiceContext, configure: Callable[[GhReleaseDownloadSettings], GhReleaseDownloadSettings] | None=None) -> ExecResult

  Download a release's assets: gh release download.

• static async release_edit(ctx: ServiceContext, configure: Callable[[GhReleaseEditSettings], GhReleaseEditSettings] | None=None) -> ExecResult

  Change a release: gh release edit.

• static async release_delete(ctx: ServiceContext, configure: Callable[[GhReleaseDeleteSettings], GhReleaseDeleteSettings] | None=None) -> ExecResult

  Remove a release: gh release delete.

• static async run_list(ctx: ServiceContext, configure: Callable[[GhRunListSettings], GhRunListSettings] | None=None) -> ExecResult

  List workflow runs: gh run list.

• static async run_list_entries(ctx: ServiceContext, configure: Callable[[GhRunListSettings], GhRunListSettings] | None=None) -> object

  The runs as parsed GhRunEntry values — the reader a build branches on. The --json field set is pinned, since gh requires one by name.

• static async run_view(ctx: ServiceContext, configure: Callable[[GhRunViewSettings], GhRunViewSettings] | None=None) -> ExecResult

  Show a run: gh run view.

• static async run_rerun(ctx: ServiceContext, configure: Callable[[GhRunRerunSettings], GhRunRerunSettings] | None=None) -> ExecResult

  Rerun a run, or its failed jobs: gh run rerun.

• static async run_cancel(ctx: ServiceContext, configure: Callable[[GhRunCancelSettings], GhRunCancelSettings] | None=None) -> ExecResult

  Stop a run: gh run cancel.

• static async run_delete(ctx: ServiceContext, configure: Callable[[GhRunDeleteSettings], GhRunDeleteSettings] | None=None) -> ExecResult

  Remove a run: gh run delete.

• static async run_download(ctx: ServiceContext, configure: Callable[[GhRunDownloadSettings], GhRunDownloadSettings] | None=None) -> ExecResult

  Fetch a run's artifacts: gh run download.

• static async run_watch(ctx: ServiceContext, configure: Callable[[GhRunWatchSettings], GhRunWatchSettings] | None=None) -> ExecResult

  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.

• static async workflow_list(ctx: ServiceContext, configure: Callable[[GhWorkflowListSettings], GhWorkflowListSettings] | None=None) -> ExecResult

  List workflows: gh workflow list.

• static async workflow_list_entries(ctx: ServiceContext, configure: Callable[[GhWorkflowListSettings], GhWorkflowListSettings] | None=None) -> object

  The workflows as parsed GhWorkflowEntry values. The --json field set is pinned, since gh requires one by name.

• static async workflow_view(ctx: ServiceContext, configure: Callable[[GhWorkflowViewSettings], GhWorkflowViewSettings] | None=None) -> ExecResult

  Show a workflow, or its YAML: gh workflow view.

• static async workflow_run(ctx: ServiceContext, configure: Callable[[GhWorkflowRunSettings], GhWorkflowRunSettings] | None=None) -> ExecResult

  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.

• static async workflow_enable(ctx: ServiceContext, configure: Callable[[GhWorkflowEnableSettings], GhWorkflowEnableSettings] | None=None) -> ExecResult

  Turn a workflow on: gh workflow enable.

• static async workflow_disable(ctx: ServiceContext, configure: Callable[[GhWorkflowDisableSettings], GhWorkflowDisableSettings] | None=None) -> ExecResult

  Turn a workflow off: gh workflow disable.

• static async secret_set(ctx: ServiceContext, configure: Callable[[GhSecretSetSettings], GhSecretSetSettings] | None=None) -> ExecResult

  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.

• static async secret_list(ctx: ServiceContext, configure: Callable[[GhSecretListSettings], GhSecretListSettings] | None=None) -> ExecResult

  List the secrets' names: gh secret list.

• static async secret_list_entries(ctx: ServiceContext, configure: Callable[[GhSecretListSettings], GhSecretListSettings] | None=None) -> object

  The secrets as parsed GhSecretEntry values — names and metadata; GitHub never returns a secret's value.

• static async secret_delete(ctx: ServiceContext, configure: Callable[[GhSecretDeleteSettings], GhSecretDeleteSettings] | None=None) -> ExecResult

  Remove a secret: gh secret delete.

• static async variable_set(ctx: ServiceContext, configure: Callable[[GhVariableSetSettings], GhVariableSetSettings] | None=None) -> ExecResult

  Store a variable: gh variable set.

• static async variable_get(ctx: ServiceContext, configure: Callable[[GhVariableGetSettings], GhVariableGetSettings] | None=None) -> ExecResult

  Read a variable: gh variable get.

• static async variable_value(ctx: ServiceContext, configure: Callable[[GhVariableGetSettings], GhVariableGetSettings] | None=None) -> object

  A variable's value, with the trailing newline gh prints removed.

• static async variable_list(ctx: ServiceContext, configure: Callable[[GhVariableListSettings], GhVariableListSettings] | None=None) -> ExecResult

  List variables: gh variable list.

• static async variable_list_entries(ctx: ServiceContext, configure: Callable[[GhVariableListSettings], GhVariableListSettings] | None=None) -> object

  The variables as parsed GhVariableEntry values, values included — a variable is not a secret.

• static async variable_delete(ctx: ServiceContext, configure: Callable[[GhVariableDeleteSettings], GhVariableDeleteSettings] | None=None) -> ExecResult

  Remove a variable: gh variable delete.

• static async cache_list(ctx: ServiceContext, configure: Callable[[GhCacheListSettings], GhCacheListSettings] | None=None) -> ExecResult

  List the Actions caches: gh cache list.

• static async cache_list_entries(ctx: ServiceContext, configure: Callable[[GhCacheListSettings], GhCacheListSettings] | None=None) -> object

  The caches as parsed GhCacheEntry values — what a build reads to decide which ones to reclaim.

• static async cache_delete(ctx: ServiceContext, configure: Callable[[GhCacheDeleteSettings], GhCacheDeleteSettings] | None=None) -> ExecResult

  Reclaim caches: gh cache delete.

• static async repo_clone(ctx: ServiceContext, configure: Callable[[GhRepoCloneSettings], GhRepoCloneSettings] | None=None) -> ExecResult

  Clone a repository: gh repo clone.

• static async repo_create(ctx: ServiceContext, configure: Callable[[GhRepoCreateSettings], GhRepoCreateSettings] | None=None) -> ExecResult

  Create a repository: gh repo create.

• static async repo_view(ctx: ServiceContext, configure: Callable[[GhRepoViewSettings], GhRepoViewSettings] | None=None) -> ExecResult

  Show a repository: gh repo view.

• static async repo_list(ctx: ServiceContext, configure: Callable[[GhRepoListSettings], GhRepoListSettings] | None=None) -> ExecResult

  List repositories: gh repo list.

• static async repo_list_entries(ctx: ServiceContext, configure: Callable[[GhRepoListSettings], GhRepoListSettings] | None=None) -> object

  The repositories as parsed GhRepositoryEntry values. The --json field set is pinned, since gh requires one by name.

• static async repo_fork(ctx: ServiceContext, configure: Callable[[GhRepoForkSettings], GhRepoForkSettings] | None=None) -> ExecResult

  Fork a repository: gh repo fork.

• static async repo_sync(ctx: ServiceContext, configure: Callable[[GhRepoSyncSettings], GhRepoSyncSettings] | None=None) -> ExecResult

  Bring a fork up to date: gh repo sync.

• static async repo_edit(ctx: ServiceContext, configure: Callable[[GhRepoEditSettings], GhRepoEditSettings] | None=None) -> ExecResult

  Change a repository's settings: gh repo edit.

• static async repo_rename(ctx: ServiceContext, configure: Callable[[GhRepoRenameSettings], GhRepoRenameSettings] | None=None) -> ExecResult

  Rename a repository: gh repo rename.

• static async repo_archive(ctx: ServiceContext, configure: Callable[[GhRepoArchiveSettings], GhRepoArchiveSettings] | None=None) -> ExecResult

  Archive or unarchive a repository: gh repo archive/unarchive.

• static async repo_delete(ctx: ServiceContext, configure: Callable[[GhRepoDeleteSettings], GhRepoDeleteSettings] | None=None) -> ExecResult

  Delete a repository: gh repo delete. Needs the delete_repo scope.

• static async repo_set_default(ctx: ServiceContext, configure: Callable[[GhRepoSetDefaultSettings], GhRepoSetDefaultSettings] | None=None) -> ExecResult

  Choose the repository gh acts on by default: gh repo set-default.

• static async label_list(ctx: ServiceContext, configure: Callable[[GhLabelListSettings], GhLabelListSettings] | None=None) -> ExecResult

  List labels: gh label list.

• static async label_list_entries(ctx: ServiceContext, configure: Callable[[GhLabelListSettings], GhLabelListSettings] | None=None) -> object

  The labels as parsed GhLabelEntry values. The --json field set is pinned, since gh requires one by name.

• static async label_create(ctx: ServiceContext, configure: Callable[[GhLabelCreateSettings], GhLabelCreateSettings] | None=None) -> ExecResult

  Add a label: gh label create.

• static async label_edit(ctx: ServiceContext, configure: Callable[[GhLabelEditSettings], GhLabelEditSettings] | None=None) -> ExecResult

  Change a label: gh label edit.

• static async label_delete(ctx: ServiceContext, configure: Callable[[GhLabelDeleteSettings], GhLabelDeleteSettings] | None=None) -> ExecResult

  Remove a label: gh label delete.

• static async label_clone(ctx: ServiceContext, configure: Callable[[GhLabelCloneSettings], GhLabelCloneSettings] | None=None) -> ExecResult

  Copy another repository's labels: gh label clone.

• static async run(ctx: ServiceContext, configure: Callable[[GhSettings], GhSettings] | None=None) -> ExecResult

  Run a gh command.

• static async api(ctx: ServiceContext, endpoint: str, configure: Callable[[GhApiSettings], GhApiSettings] | None=None) -> ExecResult

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

class GhVariableDeleteSettings(GhCommandSettings)

• name(value: str) -> Self

  The variable's name (required).

• org(name: str) -> Self

  Delete an organization variable (--org).

• environment(name: str) -> Self

  Delete an environment variable (--env).

class GhVariableGetSettings(GhReadSettings)

• name(value: str) -> Self

  The variable's name (required).

• org(name: str) -> Self

  Read an organization variable (--org).

• environment(name: str) -> Self

  Read an environment variable (--env).

class GhVariableListSettings(GhReadSettings)

• org(name: str) -> Self

  List an organization's variables (--org).

• environment(name: str) -> Self

  List an environment's variables (--env).

class GhVariableSetSettings(GhCommandSettings)

• name(value: str) -> Self

  The variable's name (required).

• body(value: str) -> Self

  Its value (--body); omit it and gh reads standard input.

• env_file(path: str) -> Self

  Read names and values from a dotenv file (--env-file).

• org(name: str) -> Self

  Scope it to an organization (--org).

• environment(name: str) -> Self

  Scope it to a deployment environment (--env).

• repositories(*names: str) -> Self

  Share an organization variable with these repositories (--repos).

• visibility(value: Literal['all', 'private', 'selected']) -> Self

  The visibility of an organization variable (--visibility).

class GhWebReadSettings(GhReadSettings)

• web() -> Self

  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.

class GhWorkflowDisableSettings(GhWorkflowTargetSettings)

class GhWorkflowEnableSettings(GhWorkflowTargetSettings)

class GhWorkflowListSettings(GhReadSettings)

• all() -> Self

  Include disabled workflows (--all).

• limit(count: float) -> Self

  Cap how many are fetched (--limit); gh's default is 50.

class GhWorkflowRunSettings(GhWorkflowTargetSettings)

• ref(name: str) -> Self

  The branch or tag to run it on (--ref).

• field(key: str, value: str | float | bool) -> Self

  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.

• raw_field(key: str, value: str | float | bool) -> Self

  An input passed verbatim (--raw-field), with no @ file syntax.

• json_input() -> Self

  Read the whole input object as JSON on standard input (--json).

class GhWorkflowTargetSettings(GhCommandSettings)

• workflow(name_or_id: str | float) -> Self

  The workflow — its file name, its name, or its id (required).

class GhWorkflowViewSettings(GhWorkflowTargetSettings)

• ref(name: str) -> Self

  The branch or tag holding the version to view (--ref).

• yaml() -> Self

  Print the workflow's YAML rather than its summary (--yaml).

• web() -> Self

  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.