github

package
v3.0.0-dev.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package github is the forgeapi client for GitHub: github.com and Enterprise Server, served by the same code. Client is its client, and ReadLimit the one reading of a GitHub answer's rate-limit facts, for a caller with its own wire; no wire type of this product reaches a forgeapi signature.

Where this product differs from the others, the method concerned says so: Client.MergePR is asynchronous, Client.ListMyPRs and Client.ListMyIssues read a search, and APIVersionHeader states how the REST version is pinned.

Index

Constants

View Source
const APIVersion = "2026-03-10"

APIVersion is the pinned REST API version: the current one, with no end of support scheduled. It supersedes 2022-11-28, which closes on 10 March 2028 and which this package's field sets were first measured against; this date's breaking changes were read against every response field. An instance that retires it answers forgeapi.CodeAPIVersionRetired, so move this constant before that date.

View Source
const APIVersionHeader = "X-GitHub-Api-Version"

APIVersionHeader is the header that pins this family's REST API version. It rides every REST request of a connection whose instance serves APIVersion, read once at connection setup from the version set the instance publishes, and no request of one whose instance does not: an unserved version is refused with 400 and no version echo, so the pin is never sent blind. A connection without the pin, or whose setup has not run, runs under the instance's default. [retiredVersion] reads the answers to pinned requests.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is one GitHub connection: where the instance is, what the credential is trusted with, and what the budget allows.

It is the concrete type New returns, so a consumer declares the narrowest role interface it actually uses against it rather than receiving an interface this package chose. What it holds is unexported, because the state behind an operation is nobody else's contract.

func New

func New(conn forgeapi.Connection, opts ...forgeapi.Option) (*Client, error)

New builds a client for one connection. It performs no I/O, so an instance that is down fails at the operation, not at construction. It refuses a missing credential source (forgeapi.CodeAnonymousRefused), a malformed connection (forgeapi.CodeConnectionInvalid), a reserved extra header (forgeapi.CodeHeaderReserved), plaintext without forgeapi.WithPlaintextHTTP (forgeapi.CodePlaintextRefused), a private host without forgeapi.WithPrivateAddresses (forgeapi.CodePrivateAddressRefused), a negative budget value (forgeapi.CodeBudgetInvalid) and a malformed cursor (forgeapi.CodeCursorInvalid).

func (*Client) AddLabels

func (c *Client) AddLabels(ctx context.Context, repo forgeapi.RepoRef, target forgeapi.LabelTarget, names []string) error

AddLabels implements forgeapi.Labels.

func (*Client) BudgetState

func (c *Client) BudgetState() forgeapi.BudgetState

BudgetState implements forgeapi.Governor: the USER's quota, shared by every application acting for the credential, as the last answer's rate-limit headers report it, never the rate-limit endpoint (measured to report a full pool while documents drew it down). Remaining is the last call's pool; Pools holds each by its X-RateLimit-Resource (core, graphql, search). LastCost is 1 per REST attempt, 0 for an authorized conditional 304, a document's reported cost where a document is its last exchange. RotationCursor is empty: a list's folded verdict is exact here. No I/O; safe concurrently.

func (*Client) CancelAutoMerge

func (c *Client) CancelAutoMerge(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef) error

CancelAutoMerge implements forgeapi.Merges.

The pull request's REST record is read first: its auto_merge is null where nothing is armed, and the call ends there, since this product's description says nothing of what the disarm document answers on a pull request with nothing armed. Otherwise the disarm is addressed by the record's node id, as the arm is. A disarm the forge refuses stays upstream with its message quoted: no capture witnesses its body.

func (*Client) Close

func (c *Client) Close()

Close implements forgeapi.Core: it releases this client's pool, the idle connections of the transport the library built for the connection, at once, which a caller that disconnects or re-addresses the connection wants; otherwise they close after that transport's idle timeout. A transport supplied through forgeapi.WithWireTransport stays its author's to release. A call in flight keeps its connection until it returns. Close adds no closed state: a call after it dials afresh, and a further Close releases that connection too.

func (*Client) CloseIssue

func (c *Client) CloseIssue(ctx context.Context, repo forgeapi.RepoRef, issue forgeapi.IssueRef) (forgeapi.Issue, error)

CloseIssue implements forgeapi.Issues. This product fills the close REASON itself on a plain close, measured, so the request sends the state alone.

func (*Client) ClosePR

ClosePR implements forgeapi.PullRequests.

func (*Client) CommitStatus

func (c *Client) CommitStatus(ctx context.Context, repo forgeapi.RepoRef, ref string) (forgeapi.CommitChecks, error)

CommitStatus implements forgeapi.Checks.

The fold is computed here rather than taken from this product's rollup verdict, because the neutral state is invisible in that field and reachable only per run. The measurement covered the endpoints it reads from, and the combined status alone is not one of them: on a repository whose CI is Actions that endpoint answers an EMPTY array, byte-identical to a commit with no CI at all, so a fold over it reports a green that is not there. The sources are the statuses and the check runs together, or the one rollup document that unions them and is the only read that tells an empty fold from a passing one. This read addresses one commit, so the fold is COMPLETE and bounded by forgeapi.Budget.StatusPages.

It is one to three requests. The document arm spends one plus a further page of the contexts connection wherever that connection has one, up to that bound; the degraded arm, which a connection takes once it has already discovered its documents refused, spends the two REST reads, plus the one further read that resolves the successor where they answered from another address, which both of them meet and one read answers. A call that meets the refusal answers with it rather than buying those two inside the same call.

func (*Client) ConnectionCaps

func (c *Client) ConnectionCaps(ctx context.Context) (forgeapi.ConnectionCaps, error)

ConnectionCaps implements forgeapi.Capabilities.

It is connection setup, and what it costs is one request or two: the version set this instance serves is read here, because which REST API version this connection runs under is a one-time fact about the instance and this is the row that prices it, and the family is established from a header this product sends on every response including a refusal, so a connection that has already sent anything needs no request for that half and one that has not reads the metadata endpoint to get it. Every answer is held with the client, so every later call costs nothing.

The one capability this scope carries is the re-run of failed checks, and it is UNKNOWN on this product by measurement rather than by omission: the workflow runner is enabled per REPOSITORY rather than per instance or per version, no connection-scope read names it, the read that answers it for one repository needs admin, and a workflow-runs read answers 200 whether the runner is enabled or merely unused. So the verdict is unknown with its evidence saying why, which renders a control with its reason, and what refuses a re-run in practice is the instance's own answer to it.

A metadata read the credential cannot make is not a failure here, and that is a decision rather than a swallow: the header still names the product, so the family IS established, and what could not be read was a version this scope's verdict does not turn on. A response carrying no such header and no prior witness is REFUSED with forgeapi.CodeFamilyUndetected, because every route, enumeration table and error mapping below this point is one family's.

func (*Client) CreateIssue

func (c *Client) CreateIssue(ctx context.Context, repo forgeapi.RepoRef, req forgeapi.NewIssue) (forgeapi.Issue, error)

CreateIssue implements forgeapi.Issues. It is ONE request: this product's issue creation takes label NAMES, so nothing has to resolve them to identifiers first, which is the difference from the pull-request creation, whose route declares no labels parameter at all. A creation that answers from another address spends the one further read that resolves the successor, which is the second request the price states.

So no second request applies them here and none is priced: measured on the creation's own response, the labels the request carried come back on the created issue, which is the same route that applies them to a pull request answering for its own population.

func (*Client) CreatePR

CreatePR implements forgeapi.PullRequests.

It is ONE request where the caller names no label and TWO where it does, which is what this product's creation takes: measured, that route declares no labels parameter at all, so a creation that sent them would have them ignored and a creation that dropped them would succeed without doing what was asked. Applying them is the ISSUES route acting on the created pull request's own number, which is the second request this operation's price states. A request of either that answers from another address spends the one further read that resolves the successor, which is the third.

A failure applying them returns the created pull request BESIDE the error, which is the one shape on this surface where a non-nil error arrives with an answer: the creation happened, so an error alone would hide an object the caller now owns, and the error names what was not done to it. The pull request carries forgeapi.PartialLabelsNotApplied on its own marker, counting every label named, because the labels request applies them all or none.

The created record carries no label row of its own either way, measured on the creation's own response, so a caller that renders the labels reads the pull request again; the departure row of this operation on this product says so.

The draft flag IS a field here, unlike the family that marks a draft with a title prefix.

func (*Client) CreateRelease

func (c *Client) CreateRelease(ctx context.Context, repo forgeapi.RepoRef, req forgeapi.NewRelease) (forgeapi.Release, error)

CreateRelease implements forgeapi.Releases. Both flags the contract carries are fields of this product's own creation, so a draft and a prerelease are what the caller asked for rather than an approximation, and a draft carries no publication instant at all, which the answer reports as the zero time.

func (*Client) GrantCaps

func (c *Client) GrantCaps(ctx context.Context) (forgeapi.GrantCaps, error)

GrantCaps implements forgeapi.Capabilities.

It costs AT MOST one request, the identity read whose response header carries what the credential is trusted with, and nothing on a connection that has already made that read.

What it publishes is whether the merge STATE is readable, and on this product that is yes whatever the grant, measured: one document answered the merge state beside a viewer permission of READ and a viewer that could not update the pull request. So routing it through an unknown would render a disabled control with a reason that is not true, and the grant-scoped unknown belongs to the family whose recheck needs a project role. What the scope header does add is the EVIDENCE, which names the scopes the credential actually holds, and a fine-grained token reports an empty set there, which is why the detail says what was read rather than inferring from it.

func (*Client) ListIssues

func (c *Client) ListIssues(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Issue], error)

ListIssues implements forgeapi.Issues.

This route's population is issues and PULL REQUESTS both on this product, and every pull-request row carries a key naming its own pull request, so a row carrying that key is dropped here: the operation publishes issues, and a list that answered pull requests among them would make a consumer's issue count wrong for free.

func (*Client) ListLabels

func (c *Client) ListLabels(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Label], error)

ListLabels implements forgeapi.Labels.

func (*Client) ListMyIssues

func (c *Client) ListMyIssues(ctx context.Context, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Issue], error)

ListMyIssues implements forgeapi.Issues.

It is the issue twin of Client.ListMyPRs: the same search connection, scoped the same way under either scope, priced the same way and ended the same way at the search's window, through a document of its own whose rows are issues and carry their own repository. It asks for the page bound as given, since a page of 100 of its rows answered under an owner where the pull-request search's did not. An owner the search index holds no account for answers an empty page with no error here too, measured.

func (*Client) ListMyPRs

ListMyPRs implements forgeapi.PullRequests.

This product answers it through a SEARCH document of its own, whose rows carry their own repository. Under forgeapi.WithOwner the owner qualifier replaces the author keyword and resolves an organization as it resolves a user; an owner the index holds no account for answers an empty page, measured, so this family cannot answer forgeapi.CodeOwnerUnresolved without a resolving read the price does not carry.

It asks for at most [prSearchPageCeiling] rows a page whatever the page bound asks, for the reason that constant states, and a page of that size cost one point under both owners measured, so the cost moves with the page, never with the repository count. The search answers no result past its 1,000th, so a walk ends there with no continuation, and the page that ends it carries forgeapi.PartialResultWindow wherever the search's own total states more than the walk was served.

func (*Client) ListPRs

ListPRs implements forgeapi.PullRequests with the list document, one request a page of at most [prListPageCeiling] rows: the REST list carries no rollup and no merge state, so this read has no REST arm, and a refused document fails the call and marks the connection. Each row's fold is bounded to one context ([listFoldPageSize]), yet its verdict and counts are exact, because the connection's per-state counts describe the whole collection ([docStateCount]); a row whose contexts continue carries forgeapi.PartialPaginationCap for the names.

func (*Client) ListReleases

func (c *Client) ListReleases(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Release], error)

ListReleases implements forgeapi.Releases.

func (*Client) ListRepos

func (c *Client) ListRepos(ctx context.Context, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Repository], error)

ListRepos implements forgeapi.Repos.

Without an owner scope it asks the identity-scoped route for the repositories the CREDENTIAL can reach, with no affiliation or visibility filter. Each row carries its own affordances but the merge strategies: this product's minimal repository representation omits all three flags, measured, so a row answers an empty set with evidence saying why and a caller that needs them pays Client.RepoAffordances.

func (*Client) ListRuns

func (c *Client) ListRuns(ctx context.Context, repo forgeapi.RepoRef, opts ...forgeapi.ListOption) (forgeapi.Page[forgeapi.Run], error)

ListRuns implements forgeapi.Checks.

A run is an Actions workflow run, the row the re-run resolves its run from: its state folds status and conclusion, its branch is the head branch, its name the run's display title and its workflow path the definition's path. A page is one request, plus one read resolving the successor where the route answered from another address, published on forgeapi.Page.Successor. It is not gated on forgeapi.CapRerunChecks, the re-run verb's, since every repository answers the route.

func (*Client) MergePR

MergePR implements forgeapi.Merges.

This is the family whose merge is ASYNCHRONOUS, and it is why a merge has an outcome rather than only a failure: the request is accepted and runs in the background, answering 202 with a handle, and it answers immediately where the pull request is already merged.

The handle this product mints for a background merge is not held: the caller reads the merge back through Client.MergeStatus on the same pull request, which reads the pull request's document. This method does not poll. A queued merge routinely outlives the per-operation deadline, so polling inside the mutation would leave no bound left to publish. It also issues no second request to read a queue position: the position lives on the queue entry the list document already selects, so it arrives with the next list read and reads forgeapi.QueuePositionUnknown in between. The 202's own body carries no queue key of any kind, measured, which is why this operation's queue verdict is unknown rather than the neutral member.

Two things the request sends are decisions rather than plumbing. The head pin is mandatory on every family, because a merge sent without a SHA merges whatever the head is now; here it rides `sha`, the key the route reads, and the pending answer echoes it as `expected_head_sha`. And nothing that DEFERS the merge is sent unless the caller set forgeapi.MergeRequest.AutoMerge: a merge this product accepts completes in the background on its own, so a deferral nobody asked for would answer a merge nobody asked to wait for, which is the defect that started this library.

A merge asked to wait reads the pull request's REST record before the merge, because this product arms an auto-merge only on a pull request that cannot merge now and refuses to arm one that can: a state that is mergeable now merges as above, and any other is armed through the enableAutoMerge document with the pin as its expected head, which answers forgeapi.MergeOutcomeEnqueued. An arm the forge refuses is forgeapi.CodeNotMergeable, its cause named in human text alone, a credential that may not merge included: no capture yet witnesses that refusal's body. forgeapi.MergeRequest.DeleteBranch reaches neither route, which take no such field; the repository's own delete-branch-on-merge setting decides.

A 409 is the route's answer to a merge sent while another is pending: its body names that merge's handle, so it is forgeapi.MergeOutcomeInFlight under forgeapi.CodeAlreadyEnqueued rather than a refusal.

func (*Client) MergeStatus

func (c *Client) MergeStatus(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef) (forgeapi.MergeStatus, error)

MergeStatus implements forgeapi.Merges.

It is ONE request on both of its arms, the single-pull-request document whose selection already carries the merged flag, the merge-queue entry and the pull request's own URL, and the REST pull-request record on a connection that has ALREADY discovered its documents refused, which carries the merged flag and the URL and answers forgeapi.QueueNone, the value that record's own absence of a merge-queue entry takes. That REST record answering from another address spends the one further read that resolves the successor, which this operation publishes on forgeapi.MergeStatus.Successor rather than refusing, and it is the second request the price states. A call that meets the refusal itself spends that one request and answers with it, so neither arm exceeds the published price, and the remedy for the caller is the next call on the same connection, which takes the REST arm from the start. So the queue verdict here has the five members that entry reports and nothing this operation returns needs a second call. It follows no page of checks: it returns none, so Client.ReadPR is what a caller wanting the folded verdict calls, on the same pull request, and this read's forgeapi.MergeStatus.WebURL is the page for a person.

It reads no merge handle: upstream's 404 on the handle endpoint does not separate an expired result from an invisible repository or a wrong pull request, so the only honest treatment of it is the document read, and a handle read that falls back to the document is TWO requests where the arm that answers publishes one.

func (*Client) PoolOf

func (c *Client) PoolOf(req *http.Request) string

PoolOf is the X-RateLimit-Resource (core, graphql, search) the operation req belongs to last drew on, for a request this client built as its hooks and wire transport receive it: empty before that operation's first answer named a pool, and for any other request. The governor holds the operation's next read against this pool. No I/O; safe concurrently.

func (*Client) ReadIssue

func (c *Client) ReadIssue(ctx context.Context, repo forgeapi.RepoRef, issue forgeapi.IssueRef) (forgeapi.Issue, error)

ReadIssue implements forgeapi.Issues.

func (*Client) ReadPR

ReadPR implements forgeapi.PullRequests.

It reads the single-pull-request document, whose field set is its own: the merge state is the slow field on a large repository, so a read must not pay a list's cost and a list must not pay a read's.

It is one to three requests: the document, plus a further page of the contexts connection wherever that connection has one, because the fold on a single-pull-request read is COMPLETE and bounded by forgeapi.Budget.StatusPages. The caller named one pull request and is owed a verdict, so this is the path that pays for one; a row of Client.ListPRs is not. Measured on a 446-context pull request, that bound is reached on a live repository and leaves the names short with the marker saying so.

The degraded REST path spends ONE, plus the one further read that resolves the successor where that record answered from another address, and it is the arm a connection takes once it has already discovered this instance refusing the document: no page of a fold follows it, because REST carries no checks rollup to follow and forgeapi.ActionState.Checks is forgeapi.CheckUnknown for that connection. The call that MEETS the refusal fails with it rather than falling back inside itself, so a discovery is never a second request charged to whichever operation happened to arrive first.

Its two absence answers are separated by evidence rather than by status, and the evidence is free here because the document already decodes it: a resolved repository with no pull request is forgeapi.CodePRNotFound, a null repository is forgeapi.CodeRepoOrPRNotVisible, and the degraded REST path reports the union because there the status is all there is.

func (*Client) RemoveLabels

func (c *Client) RemoveLabels(ctx context.Context, repo forgeapi.RepoRef, target forgeapi.LabelTarget, names []string) error

RemoveLabels implements forgeapi.Labels. This product's removal answers 404 for a label the item lacks and for a missing item alike, so the first 404 reads the item once: found, that 404 and every later one is a name not carried.

func (*Client) ReopenIssue

func (c *Client) ReopenIssue(ctx context.Context, repo forgeapi.RepoRef, issue forgeapi.IssueRef) (forgeapi.Issue, error)

ReopenIssue implements forgeapi.Issues.

func (*Client) ReopenPR

func (c *Client) ReopenPR(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef) (forgeapi.PullRequest, error)

ReopenPR implements forgeapi.PullRequests.

func (*Client) RepoAffordances

func (c *Client) RepoAffordances(ctx context.Context, repo forgeapi.RepoRef) (forgeapi.RepoAffordances, error)

RepoAffordances implements forgeapi.Capabilities from the repository's own record, read on every call and revalidated while the read cache is on, so an unchanged record's not-modified answer bills nothing when the request carries an Authorization header. A merge queue is a ruleset property here, which the record carries on neither route and which costs a request per ruleset to read, so forgeapi.RepoAffordances.MergeTrain is forgeapi.SupportUnknown with default evidence. A listing row carries no merge-strategy flags (measured), so a caller that needs forgeapi.RepoAffordances.MergeStrategies pays this read.

func (*Client) RerunFailedChecks

func (c *Client) RerunFailedChecks(ctx context.Context, repo forgeapi.RepoRef, pr forgeapi.PRRef, headSHA string) error

RerunFailedChecks implements forgeapi.PullRequests: the run re-run is the one [Client.rerunTarget] resolves. It is not gated on forgeapi.CapRerunChecks, whose verdict is unknown at connection scope: the runner is enabled per repository, the read naming it needs admin, and a runs read answers 200 either way, so a refusal here is the instance's own.

func (*Client) RerunFailedRun

func (c *Client) RerunFailedRun(ctx context.Context, repo forgeapi.RepoRef, run forgeapi.RunRef) error

RerunFailedRun implements forgeapi.Checks: one POST to the failed-jobs re-run of the run, plus the successor read where it answered from another address. Like Client.RerunFailedChecks it is not gated on forgeapi.CapRerunChecks, whose verdict this product cannot read per connection.

func (*Client) Whoami

func (c *Client) Whoami(ctx context.Context) (forgeapi.Account, error)

Whoami implements forgeapi.Identity. This product reports the credential's granted scopes in a response HEADER rather than in the account body, which was measured on a classic OAuth token, so a grant capability rests on evidence rather than on inference. A fine-grained token is documented to report an empty set there and was not measured, so on that credential kind the same capability degrades to unknown rather than to none. The account body's own email is the PUBLIC profile one and is null where the profile carries none.

type RateLimit

type RateLimit struct {
	// Reset is X-RateLimit-Reset as sent, whatever Remaining reads; the zero
	// time where absent or unreadable.
	Reset time.Time
	// Pool is X-RateLimit-Resource as sent, a secondary limit's included;
	// empty where absent.
	Pool string
	// RetryAfter is the wait Retry-After asks for, zero where absent.
	RetryAfter time.Duration
	// Remaining is X-RateLimit-Remaining as sent;
	// [forgeapi.BudgetRemainingUnknown] where absent or unreadable.
	Remaining int
	// Limit is X-RateLimit-Limit as sent, zero where absent.
	Limit int
	// Limited reports a rate limit: a 429, or a 403 carrying Retry-After,
	// X-RateLimit-Remaining 0 or the secondary-limit message.
	Limited bool
	// Secondary reports a secondary limit: Limited, and the body's JSON
	// message member names a secondary rate limit or the answer carries
	// Retry-After.
	Secondary bool
}

RateLimit is what one GitHub answer says about its rate limits, read from that answer alone: each figure is the answer's own header, on any answer, a success's included (https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api).

func ReadLimit

func ReadLimit(status int, h http.Header, body []byte) RateLimit

ReadLimit reads one GitHub answer's rate-limit facts from its status, its header and its body, the one reading the client's forgeapi.Error figures and the creds package's App mint take. The secondary-limit message is the body's JSON message member carrying "secondary rate limit" in any case; the phrase anywhere else, or in a body that is not JSON, is none.

Directories

Path Synopsis
Package githubtest is GitHub's rate-limit answers as cases a GitHub classifier runs: what github.ReadLimit, or the github client's GraphQL document path, reads from each, the kind the github client's error answers it with, and the effect a classifier answers its gate with (https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api, https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api).
Package githubtest is GitHub's rate-limit answers as cases a GitHub classifier runs: what github.ReadLimit, or the github client's GraphQL document path, reads from each, the kind the github client's error answers it with, and the effect a classifier answers its gate with (https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api, https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL