# @effected/github constructs | Construct | Kind | Purpose | Reach for it when | | --- | --- | --- | --- | | `ActionsOidc` | Class | Verify GitHub Actions OIDC tokens: a workflow proving to your service which repository, workflow and run it is. | verify a github actions oidc token from a workflow, authorize a ci caller by repository id | | `ActionsOidcClaims` | Class | The claims of a verified GitHub Actions OIDC token. | typed claims of a verified actions oidc token, repository id, run id, job workflow ref | | `ActionsOidcClaimsFromWire` | Variable | `ActionsOidcClaims` as the claims arrive in the token: snake_case keys and string ids, decoding to the class and encoding back to the wire. | decode or encode actions oidc claims as the token carries them, `snake_case` keys and string ids | | `ActionsOidcVerifyOptions` | Interface | Options for `ActionsOidc.verify`. | | | `Annotation` | Class | One annotation on a check run. | one file annotation on a check run, notice or warning at a line range | | `AnnotationLevel` | Variable | How serious an annotation is. | notice warning failure severity for a check run annotation | | `AppCredentials` | Interface | The credentials that identify a GitHub App. | | | `AppIdentity` | Class | What GitHub knows about the app itself. | resolve the github app's slug name and bot user id | | `AppInfo` | Class | The GitHub App itself, as `GET /app` reports it. | the github app's own id slug name and node id from GET /app | | `AppliedSettings` | Interface | What `GitHubRepositoryShape.applySettings` actually sent. | | | `ApplySettingsOptions` | Interface | Options for `GitHubRepositoryShape.applySettings`. | | | `ArtifactMetadata` | Class | Records where published artifacts are stored, at the organization level. | record where a published package artifact lives, org-level storage record, supply chain provenance | | `ArtifactMetadataShape` | Interface | Organization-level artifact metadata. | | | `Attestation` | Class | Uploads signed attestation bundles to a repository and lists what is attested about a subject digest. | upload a sigstore bundle, list attestations for a subject digest, slsa lookup | | `AttestationListEntry` | Class | One entry from an attestation listing. | one attestation bundle url and predicate type from a listing | | `AttestationRecord` | Class | A stored attestation. | a stored attestation's id and url after upload | | `AttestationShape` | Interface | The attestation REST surface. | | | `AuthenticatedApp` | Class | The app-level REST surface: the app's own record, its webhook delivery log and redelivery, and uninstalling. | app jwt surface: read the app, webhook deliveries, redeliver, uninstall an installation | | `AuthenticatedAppShape` | Interface | The app-level REST surface: the app's own record, its webhook deliveries and removing an installation. | | | `BotIdentity` | Class | Who a bot commits as. | committer name and email for a bot commit, dco signoff trailer, github-actions bot identity | | `BotUser` | Class | An app's bot user: the account its installation tokens act as. | a github app bot user's id and login, matched against event actor ids | | `BotUserRequest` | Interface | What `GitHubAppShape.botUser` looks up. | | | `BranchOutcome` | TypeAlias | What `GitBranchShape.upsert` did. | | | `CachedToken` | Interface | An installation token from `GitHubApp.cachedToken`, and where it came from. | | | `CachedTokenRequest` | Interface | What to fetch a cached installation token for. | | | `ChangelogInfo` | Class | The commit and pull request facts a changelog line credits, batched into one GraphQL query. | changelog line credit for a commit or pull request, batched graphql, replaces get-github-info | | `ChangelogInfoShape` | Interface | The commit and pull request facts a changelog line credits. | | | `CheckConclusion` | Variable | How a check run finished. | success failure neutral cancelled timed_out action_required skipped, how a check run finished | | `CheckRun` | Class | Create, update and conclude GitHub check runs, including the `CheckRunShape.withCheckRun` bracket that always reaches a terminal state. | report a job's verdict on a commit, create update complete a run, find a run by external id | | `CheckRunOutput` | Class | A check run's rendered output. | check run title summary and annotations, truncate to github's 65535 byte limit | | `CheckRunRef` | Class | A check run as GitHub reports it. | a check run as github reports it: status, conclusion, head sha, urls, timestamps, output | | `CheckRunShape` | Interface | Create, update and conclude GitHub check runs on a commit, including a bracket that always concludes the run. | | | `CheckRunStatus` | Variable | The phase of its lifecycle a check run is in, as GitHub reports it. | queued `in_progress` completed waiting requested pending, a check run's reported lifecycle phase | | `CodeScanning` | Class | Configure CodeQL default setup and read the languages GitHub detects in a repository. | configure codeql default setup, detect repository languages for codeql, enable codeql scanning | | `CodeScanningSetup` | Interface | A CodeQL default-setup configuration. | | | `CodeScanningShape` | Interface | CodeQL default setup, and the language detection that gates it. | | | `CommentMarker` | Class | The hidden marker that makes a comment findable again. | hidden html marker that makes a sticky comment findable again, namespaced comment key | | `CommentOnceResult` | Class | What `GitHubIssueShape.commentOnce` found or wrote. | whether commentOnce posted a new comment or found the marker already there | | `CommentRecord` | Class | A comment this package wrote or found: its id, body and web URL. | id body and url of a comment this package wrote or found | | `CommitChangelogInfo` | Class | What a changelog line says about one commit. | commit author login, pull request number and markdown links for a changelog line | | `CommitComparison` | Class | The result of comparing two refs. | diff between two refs, ahead/behind counts, commits and changed files | | `CommitFile` | Class | One changed file. | one file's path status additions deletions from a commit or comparison | | `CommitRef` | Class | A commit, projected to the three fields callers actually use. | a commit's sha, tree sha, and parent shas for building a tree | | `CommitSummary` | Class | A commit, projected to what callers read. | a commit projected to sha message author and parents | | `CompleteCheckRunOptions` | Interface | Options for `CheckRunShape.complete`. | | | `ConcludeCheckRun` | TypeAlias | Conclude the surrounding `CheckRunShape.withCheckRun` explicitly. | | | `CreateCheckRunOptions` | Interface | Options for `CheckRunShape.create`. | | | `CreatedCommit` | Class | A commit just created through the Git Database API: its sha and the URL GitHub reports for viewing it. | a just-created commit's sha and its html_url, including on github enterprise server | | `DeliveriesOptions` | Interface | Options for `AuthenticatedAppShape.deliveries`. | | | `DeliveryAttempt` | Class | One delivery of the app's webhook, as `GET /app/hook/deliveries` lists it. | one webhook delivery attempt: id guid status code event action installation | | `DeploymentEnvironment` | Class | Create or update, list and delete a repository's deployment environments. | create update list and delete a deployment environment, environment protection rules | | `DeploymentEnvironmentInfo` | Interface | A deployment environment, as listing returns it. | | | `DeploymentEnvironmentShape` | Interface | Create or update, list and delete a repository's deployment environments. | | | `DispatchedRun` | Class | The run a `workflow_dispatch` created, as GitHub reports it when asked. | the run id and urls github returns when a workflow dispatch is asked for run details | | `ExpiringUserTokens` | Class | A user-to-server token pair that expires: what GitHub issues to a GitHub App with "Expire user authorization tokens" turned on, which is the default. | user access and refresh token pair, check expiry, persist a user grant | | `ExtraPermission` | Class | A permission the token has and did not need. | a permission a token was granted beyond what was required | | `FileChange` | Variable + TypeAlias | One change in a commit. | a file content write or deletion to include in a commit's tree | | `FileContent` | Class | A file to write in a commit. | a file to write in a commit, path content and blob mode | | `FileDeletion` | Class | A file to remove in a commit. | a file to remove in a commit by path | | `FileMode` | Variable | A blob's file mode, as the Git Database API spells it. | git blob file mode literals for the git database api, 100644 100755 120000 | | `FileStatus` | Variable | How a file changed in a commit or a comparison. | added removed modified renamed copied changed unchanged, how a file changed | | `GRAPHQL_ONLY_SETTINGS` | Variable | Settings written through the GraphQL `updateRepository` mutation, mapped from snake_case keys to camelCase GraphQL input fields. | repository settings reachable only through the graphql updateRepository mutation | | `GitBranch` | Class | Create, move, read and delete branch refs through GitHub's Git Database API, with an `upsert` that needs no existence check. | create reset delete a branch ref, link a branch to an issue | | `GitBranchShape` | Interface | Branch refs in GitHub's Git Database API. | | | `GitCommit` | Class | Read commits and build trees and commits through GitHub's Git Database API, including a one-call "commit these files onto a branch". | build a git tree and commit files onto a branch | | `GitCommitShape` | Interface | Commits and trees in GitHub's Git Database API. | | | `GitHubApp` | Class | GitHub App authentication: mint, revoke and identify. | mint scope revoke installation tokens, client as the app via jwt, cache tokens across requests | | `GitHubAppError` | Class | A GitHub App call failed. | a github app authentication call failed, jwt token revoke identity or installation lookup failure | | `GitHubAppOptions` | Interface | Transport settings for the app's own API calls. | | | `GitHubAppShape` | Interface | The app-authentication surface. | | | `GitHubClient` | Class | The typed GitHub API client. | the typed github rest and graphql transport: one request, one paginated read | | `GitHubClientOptions` | Interface | How a client layer is built. | | | `GitHubClientShape` | Interface | The typed GitHub transport: one request, one paginated read, one GraphQL document, and whatever the rate-limit headers last said. | | | `GitHubCommit` | Class | Read commits, compare refs and list changed files through GitHub's commits API. | read a commit, list commits on a ref, compare two refs | | `GitHubCommitShape` | Interface | Read commits, list them, compare two refs and list the files a commit touched. | | | `GitHubContent` | Class | Read a text file out of a repository at a ref, with absence as an `Option` when you want it. | read a text file's contents out of a repository at a ref | | `GitHubContentShape` | Interface | Read a text file out of a repository at a ref. | | | `GitHubError` | Class | Every REST failure this package produces, from every resource. | rest api failure taxonomy, classify notFound alreadyExists rateLimited, classify a raw http response | | `GitHubErrorKind` | Variable | Why a GitHub call failed, as a value you can branch on. | notFound alreadyExists rejected unauthorized rateLimited transport decode, structural routing for a github rest failure | | `GitHubFixtures` | Class + Interface | Builders for `(GitHubFixtures:interface)` entries. | recorded github responses for a fixture client, record a raw failure status headers body | | `GitHubGraphQLError` | Class | A GraphQL call failed. | classify a failed github graphql call, errors array in a 200 response | | `GitHubIssue` | Class | Read, list, close and comment on issues, and resolve the issues a pull request closes. | get list close and comment on an issue, post a marked comment | | `GitHubIssueShape` | Interface | Read, list, close and comment on issues, and resolve the issues a pull request closes. | | | `GitHubRelease` | Class | Create, read, list and update GitHub releases, and upload and list their assets. | create update and list releases, upload a release asset, get a release by tag | | `GitHubReleaseShape` | Interface | Create, read, list and update releases, and upload and list their assets. | | | `GitHubRepository` | Class | Read and update a repository's settings, including settings only GraphQL can write, read and replace its topics, and look up its default branch, node id and owner type. | read patch repository settings, apply settings blob across rest graphql | | `GitHubRepositoryShape` | Interface | Read and update a repository's settings and topics, and look up its default branch, node id and owner type. | | | `GitHubUserAuth` | Class | The OAuth web flow a GitHub App (or an OAuth App) uses to act as a user: PKCE code exchange, refresh, and grant revoke. | oauth web flow, exchange a code for user tokens, refresh, revoke a grant, pkce | | `GitHubUserAuthError` | TypeAlias | Every failure of a `GitHubUserAuth` operation: final (reconnect or reconfigure) or temporary (retry later). | | | `GitHubUserAuthFinal` | Class | GitHub refused the call, and repeating it will not change the answer. | oauth refused, reconnect or reconfigure remedy, bad refresh token, sign in again | | `GitHubUserAuthOperation` | Variable + TypeAlias | The decoded type of `(GitHubUserAuthOperation:variable)`. | which oauth step failed: exchange, refresh or revoke | | `GitHubUserAuthOptions` | Interface | How a `GitHubUserAuth` layer is built. | configure the oauth client id and secret, enterprise server token url, timeout | | `GitHubUserAuthShape` | Interface | The operations of `GitHubUserAuth`. | | | `GitHubUserAuthTemporary` | Class | The call did not get an answer GitHub meant: try it again later. | oauth network, timeout, 5xx or malformed reply, retry later, keep tokens | | `GitHubUserTokens` | Variable + TypeAlias | The decoded type of `(GitHubUserTokens:variable)`: `ExpiringUserTokens` `\|` `NonExpiringUserTokens`. | decode or persist a user's oauth tokens, expiring or non-expiring union | | `GitHubValidationCode` | Variable | The validation codes GitHub documents for a 422's `errors[].code`. | missing missing_field invalid already_exists unprocessable custom, github 422 validation error codes | | `GitHubValidationEntry` | Class | One entry from a failed response's `data.errors` array, as GitHub sent it. | one entry from a failed rest response's errors array, resource field code and message | | `GitTag` | Class | Create, move, resolve, list and delete tag refs through GitHub's Git Database API, and find the newest version-shaped tag. | create reset resolve and delete a tag ref, find newest semver-shaped tag | | `GitTagShape` | Interface | Tag refs in GitHub's Git Database API. | | | `GraphQLDocument` | Class | A named GraphQL document, its variables, and how to read its answer. | a named graphql query or mutation, its variables and response codec, typed graphql call | | `GraphQLErrorEntry` | Class | One entry from a GraphQL response's `errors` array. | one entry from a graphql response's errors array, message and github's error type | | `Installation` | Class | One installation of the app. | one installation of a github app, installation id and account | | `InstallationToken` | Class | An installation access token and what GitHub said about it. | a minted app installation token, expiry and permissions, re-mint before it expires | | `InstallationTokenStore` | Class | Where `GitHubApp.cachedToken` keeps installation tokens between request scopes. | cache installation tokens across requests or worker isolates, kv-backed token store seam | | `InstallationTokenStoreShape` | Interface | The operations of an `InstallationTokenStore`. | | | `InvalidChangelogRefError` | Class | A changelog lookup was handed a commit sha or pull request number it cannot send. | changelog lookup refused a non-hex sha or non-positive pull request number | | `InvalidRepoRefError` | Class | A repository slug was not `owner/repo`. | a repository slug was not owner/repo, malformed repo ref parse failure | | `IssueInfo` | Class | An issue, projected to what callers read. | an issue's number title state labels and node id, projected for callers | | `LatestSemverOptions` | Interface | How to pick the newest version-shaped tag. | | | `LinkedIssue` | Class | An issue a pull request closes. | an issue a pull request closes, whether linked manually or github-inferred | | `ListCheckRunsOptions` | Interface | Options for `CheckRunShape.list`. | | | `MergeMethod` | Variable | How a pull request is merged. | merge squash rebase, how a pull request is merged | | `NonExpiringUserTokens` | Class | A user access token that does not expire: what GitHub issues to an OAuth App, or to a GitHub App with "Expire user authorization tokens" turned off. It carries no refresh token and no expiry. | user access token with no expiry and no refresh token | | `OwnerType` | TypeAlias | Whether an account is a user or an organization. | | | `PageOptions` | Class | How far a paginated read should go. | how many items per page and how many pages to walk | | `PermissionGap` | Class | A permission the token does not have enough of. | a permission a token is missing or holds too weak a level of | | `PermissionLevel` | Variable + TypeAlias | How much access a permission grants. | read write admin, how much access a permission grants | | `PermissionResult` | Class | What comparing a token's permissions against a requirement found. | what comparing a token's permissions against a requirement found, missing and extra permissions | | `PollOptions` | Interface | How often to poll for a dispatched run, and how long to keep polling. | | | `PullRequest` | Class | Read, list, create, update, merge and label pull requests, and control auto-merge. | get list create update and merge a pull request, request reviewers | | `PullRequestChangelogInfo` | Class | What a changelog line says about one pull request. | pull request author, merge commit and markdown links for a changeset pr override | | `PullRequestComment` | Class | Post, update, find and delete comments on a pull request or issue, including a "sticky" comment kept current through a `CommentMarker`. | post or update a sticky marked comment on a pull request | | `PullRequestCommentShape` | Interface | Post, update, find and delete comments on a pull request or issue, including a "sticky" comment kept current through a marker. | | | `PullRequestInfo` | Class | A pull request, projected to what callers read. | a pull request's number head base sha state and merge status, projected for callers | | `PullRequestShape` | Interface | Read, list, create, update, merge and label pull requests, and control auto-merge. | | | `RateLimitSnapshot` | Class | What GitHub's rate-limit headers said on the most recent REST response. | what github's rate-limit headers said on the last response, remaining requests and reset time | | `RawFailure` | Class | A raw HTTP failure recorded for `GitHubClient.layerFixture`, made by `(GitHubFixtures:class).failure`. | a raw github error response recorded in a fixture, classified at call time | | `RecordedCall` | Interface | One call served by `GitHubClient.layerFixture`, as recorded in `(GitHubFixtures:interface).requested`. | | | `ReleaseAsset` | Class | A file attached to a release. | a file attached to a release, its download url and size | | `ReleaseInfo` | Class | A release, projected to the fields callers read. | a release's tag name body draft/prerelease flags and upload url | | `Repo` | Class | The repository the surrounding program acts on. | which repository the surrounding program acts on, provide a repo coordinate | | `RepoRef` | Class | Which repository an operation acts on. | parse an owner/repo slug into owner and repo, the pure repository coordinate value | | `ReportedCheckConclusion` | Variable | How a check run finished, as GitHub reports it: every `CheckConclusion` plus `"stale"`. | how a check run finished as github reports it, including stale | | `ReportedCheckRunOutput` | Class | The rendered output a check run reports: its title and summary, and how many annotations it carries. | a check run's reported output title summary and annotation count | | `RepositoryPatch` | TypeAlias | The fields `PATCH /repos/{owner}/{repo}` accepts, minus the coordinate and the per-request transport options. | | | `RepositoryPatchDraft` | TypeAlias | A `RepositoryPatch` under construction, where an absent field may be spelled as an explicit `undefined`. | | | `RepositoryPatchExtra` | TypeAlias | Repository settings the generated `RepositoryPatch` type does not know yet, for `RepositoryPatchOptions.extra`. | | | `RepositoryPatchOptions` | Interface | Options for `repositoryPatch`. | | | `RepositoryPatchReservedKey` | TypeAlias | Names `repositoryPatch` refuses in a draft or an extra. | | | `RepositorySecret` | Class | Write, list and delete repository and environment secrets, encrypted client-side before they leave the process. | encrypt and write a repository or environment secret via sealed box | | `RepositorySecretShape` | Interface | Write, list and delete Actions, Dependabot and Codespaces secrets on a repository, and Actions secrets on its environments. | | | `RepositorySecurity` | Class | Read and toggle Dependabot alerts, Dependabot security fixes and private vulnerability reporting. | toggle dependabot vulnerability alerts, automated security fixes, private vulnerability reporting inbox | | `RepositorySecurityShape` | Interface | Read and toggle the three repository security features that have their own endpoints: Dependabot alerts, Dependabot security fixes and private vulnerability reporting. | | | `RepositorySettings` | TypeAlias | Everything GitHub reports about a repository. | | | `RepositoryVariable` | Class | Create or update, list and delete Actions variables on a repository and on its environments. | create update list and delete a repository or environment variable, github actions variables | | `RepositoryVariableShape` | Interface | Create or update, list and delete Actions variables on a repository and on its environments. | | | `RestData` | TypeAlias | The `data` payload `Route` returns. | | | `RestExtras` | Interface | Transport knobs octokit accepts on any route, narrowed to the two this package allows. | | | `RestItem` | TypeAlias | One element of a paginating route's collection. | | | `RestPaginatingRoute` | TypeAlias | The subset of routes that paginate. | | | `RestParams` | TypeAlias | The parameters `Route` accepts — path, query and body parameters from GitHub's OpenAPI description, plus the extras below. | | | `RestResponse` | TypeAlias | The full response `Route` returns, including `status`, `headers` and `data`. | | | `RestRoute` | TypeAlias | Every REST route GitHub documents, as a `" "` literal — for example `"GET /repos/{owner}/{repo}"`. | | | `RetryPolicy` | Class | How the client retries a failed request. | how the client retries a failed request: backoff, jitter, retry-after delay | | `RetryableFailure` | Interface | The shape `RetryPolicy` needs from a failure to decide anything. | | | `Ruleset` | Class | Create or update, list and delete repository rulesets, and look up the team and role ids their bypass actors need. | create update list delete a repository ruleset, bypass actor lookup | | `RulesetInfo` | Interface | A ruleset, as listing returns it. | | | `RulesetPayload` | Interface | What a ruleset write sends. | | | `RulesetShape` | Interface | Create or update, list and delete repository rulesets, and look up the team and role ids their bypass actors need. | | | `SECURITY_ANALYSIS_STATUS_FIELDS` | Variable | Fields in the user-facing `security_and_analysis` block that GitHub accepts as `{ status: "enabled" \| "disabled" }`. | which security_and_analysis fields github accepts as an enabled/disabled status object | | `SecretInfo` | Interface | A secret, as listing returns it. | | | `SecretScope` | TypeAlias | Which secret store an operation acts on. | | | `SemverTag` | Class | A tag whose name carries a version. | a tag whose name carries a parsed semantic version, tag sha and version together | | `StorageRecordInput` | Class | What to record about a published artifact. | what to record about a published artifact's location, name digest registry and repository | | `TagRef` | Class | A tag and the commit it ultimately points at. | a tag name and the sha it dereferences to, annotated tag | | `TokenPermissionError` | Class | A token asked for access it does not have, or has access it did not ask for. | a token lacks access it needs, or holds access it never requested | | `TokenPermissions` | Class | The permissions a token was granted, and what they satisfy. | compare a token's granted permissions against a requirement, assert sufficient scopes | | `TokenRequest` | Interface | What to mint an installation token for. | | | `UpdateCheckRunOptions` | Interface | Options for `CheckRunShape.update`. | | | `UpsertedPullRequest` | Interface | What `PullRequestShape.upsert` did. | | | `UserAuthExchangeRequest` | Interface | The code a user brought back from GitHub's authorize page. | | | `UserAuthRefreshRequest` | Interface | A refresh token to renew. | | | `UserAuthRevokeRequest` | Interface | A user's grant to revoke. | | | `VariableInfo` | Interface | A variable's name and value, as listing returns it. | | | `VersionFromTag` | TypeAlias | Read a version out of a tag name. | | | `WorkflowDispatch` | Class | Dispatch workflows, wait for the run they start, and list the repository's workflows. | trigger a workflow dispatch event and get back the run it created, poll a dispatched run until it finishes, cancel a run | | `WorkflowDispatchShape` | Interface | Dispatch workflows, wait for the run they start, and list the repository's workflows. | | | `WorkflowInfo` | Interface | One workflow defined in the repository. | | | `WorkflowRunStatus` | Class | Where a workflow run has got to. | a workflow run's id status and conclusion, whether a dispatched run has finished | | `repositoryPatch` | Function | A `RepositoryPatch` from a draft, dropping every explicitly-`undefined` field, plus any settings octokit's types do not know yet. | build a repository settings patch from a draft, drop unset fields | | `transformSecurityAndAnalysis` | Function | Translate a user-facing `security_and_analysis` block into the shape `PATCH /repos/{owner}/{repo}` expects. | translate a security_and_analysis block into the shape the repository patch endpoint expects | | `versionFromTag` | Variable | The default `VersionFromTag`. | extract a version string out of a tag name, the default tag-to-semver convention |