gitea

package
v3.0.0-dev.10 Latest Latest
Warning

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

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

Documentation

Overview

Package gitea is the forgeapi client for Gitea and Forgejo, two products that share one API. Client is its one exported type, so no wire type of either product reaches a forgeapi signature.

Neither product has a GraphQL API, so every operation is REST and pays in requests for what a document carries on the other families. Client.CommitStatus states the largest such cost.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

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

Client is one connection to a Gitea-family instance: where it 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; the stable connection facts, which product of the two answered included, are published through Client.ConnectionCaps.

func New

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

New builds a client for one connection. It performs no I/O: which product the instance runs, and every capability its version decides, is resolved by the accessor that needs it. 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. A read that meets a move refuses with the successor and nothing is written, as [Client.labelIDs] states.

func (*Client) BudgetState

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

BudgetState implements forgeapi.Governor; what it reads depends on the PRODUCT. Forgejo's structured `ratelimit` header gives Remaining (its `r`), Reset (its `t` seconds) and forgeapi.BudgetState.Pools as that one figure under no name; Gitea sends none, so Remaining is forgeapi.BudgetRemainingUnknown, Reset the zero time and Pools empty, and the reserve is inert there. LastCost is this library's own price, one per request, since neither product prices a call; the folded-status work is bounded by forgeapi.Budget's per-interval caps, whose rotation forgeapi.BudgetState.RotationCursor holds. 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 cancel route answers 404 for a pull request with nothing scheduled and for a missing one alike (routers/api/v1/repo/pull.go CancelScheduledAutoMerge on each product), so a 404 is followed by the pull-request read: finding the pull request means nothing was scheduled, and the read's own refusal answers otherwise.

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.

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.

This is the family whose folded status costs one request per pull request, plus one per additional status page, and the fold is computed HERE rather than taken from the endpoint's own verdict: that endpoint is paginated, and both its folded state and its total are computed over the page it returned, so a page of successes reports success for a commit that is failing and the truncation is not detectable from the body at all.

So a fold that stopped short reports the pagination cap in its partial marker and leaves the state unknown rather than publishing a verdict over part of the evidence. This read addresses one commit, so its fold is COMPLETE and bounded only by forgeapi.Budget.StatusPages.

It is also the read forgeapi.Budget.StatusReadsPerInterval counts, over a rolling window this client keeps for itself: the read past that cap is not issued and reports forgeapi.PartialBudget, and the next interval starts at the row after the last one served in that LIST rather than at the first, so no row starves. What survives a restart is the forgeapi.RotationCursor a consumer stored and handed to forgeapi.WithRotationCursor.

func (*Client) ConnectionCaps

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

ConnectionCaps implements forgeapi.Capabilities.

func (*Client) CreateIssue

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

CreateIssue implements forgeapi.Issues.

func (*Client) CreatePR

CreatePR implements forgeapi.PullRequests.

func (*Client) CreateRelease

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

CreateRelease implements forgeapi.Releases.

func (*Client) GrantCaps

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

GrantCaps implements forgeapi.Capabilities.

It costs no request and carries no evidence object, and both follow from the same fact: this product has no grant endpoint, and the one grant-dependent value on this surface, the merge state, rides the pull-request record's own mergeable flag, which every read of a pull request already carries. So a credential that can read a pull request can read its merge state, and there is nothing separate to probe.

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 on both products is issues AND pull requests, so the type filter both documents declare is part of the question rather than an option: without it the answer carries pull-request rows, which this operation would normalize as issues and a consumer would act on as issues.

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 Client.ListMyPRs asking the same route for the other population: the type filter both products declare selects issues, and the scope, the price and the owner refusal are that call's own. Each row carries its own repository as the meta shape the search route answers, which is what the row is addressed by.

func (*Client) ListMyPRs

ListMyPRs implements forgeapi.PullRequests.

This family answers the cross-repository question through the ISSUE search route, filtered to pull requests and to the open state, so the rows span repositories and each carries its own forgeapi.PullRequest.Repo.

The filter that makes the rows the CREDENTIAL's is the boolean both products declare on this route, created, which the instance resolves against whoever the request authenticated as. Beside it one of the two declares a username filter, created_by, and the other declares none at all, so a call built on that spelling is contracted to scope the answer on one product of the family and not on the other. The shared boolean also prices the call at one request per page, because nothing has to be resolved before the question can be asked.

Under forgeapi.WithOwner the owner filter both products declare on the same route takes the boolean's place, so the call is still one request per page and the owner is resolved by the instance rather than by a read of its own. An owner the instance holds no user or organization for is answered 400 naming the user it could not find, which this family maps to forgeapi.CodeOwnerUnresolved: the route answers 400 for an owner or a team it cannot resolve, and this call sends no team.

No row of this route carries a folded verdict, and the reason is the route's own shape rather than a choice: an issue-search row carries neither a check state nor a HEAD COMMIT, measured on both products and declared by both documents, and a folded status is addressed BY the head. So every row answers forgeapi.CheckUnknown with a zero total, uniformly, which is what the expectation table states field by field for this operation on this family. The verdict for a row a consumer opens is Client.ReadPR or Client.CommitStatus, one call on one pull request; recovering the head here would cost a second read per row, which is the per-item fan-out the budget refuses on a poller's hot path.

func (*Client) ListPRs

ListPRs implements forgeapi.PullRequests. Each row's status fold and, under forgeapi.WithReviews, its reviews are one page each, read in rotation order under the client's per-interval cap: a status with a further page answers forgeapi.CheckUnknown with forgeapi.PartialPaginationCap, and a row the cap leaves unread carries forgeapi.PartialBudget. The rotation is this repository's own, so no row starves across intervals, and nothing schedules across repositories. Client.ListMyPRs folds nothing, since an issue-search row carries no head.

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.

Under an owner it reads the owner's own route, which both products resolve for a user and an organization alike and which pages in SQL before dropping the rows the caller has no unit access to, so its walk continues from the stated total. Its 404 is an owner the instance does not hold (services/context/user.go), so it carries forgeapi.CodeOwnerUnresolved.

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. The row type reads both products' status fields, forgeapi.Run.WorkflowPath is the workflow file's name and forgeapi.Run.Name that name without its YAML extension, since neither product names the workflow. It is not gated on forgeapi.CapRerunChecks, since both carry the route whether or not they can re-run. The envelope's total_count decides the continuation (see runWalk.next), so one missing or below zero is refused, a page with no row while the total states more ends the walk with forgeapi.PartialResultWindow, and under forgeapi.WithSince a page runsSince reports passed ends it complete.

func (*Client) MergePR

MergePR implements forgeapi.Merges.

The merge is synchronous here and this family has neither a merge queue nor a merge train, so a merge not asked to wait is merged or refused. A merge asked to wait sends the merge form first, which merges a pull request whose requirements are met, and only on that form's 405 sends it again with merge_when_checks_succeed, this family's own field for it, whose 201 is the scheduled merge, forgeapi.MergeOutcomeEnqueued: measured, every product of the family schedules a flagged merge whatever the checks, and Forgejo then waits for the next commit status on its head, so the flag goes only where the merge cannot complete now. Such a merge costs one or two requests, plus the record read at the default intent. Two of its refusals are this family's own: a conflict is forgeapi.CodeNotMergeable, because the route answers it for a head that moved, for a merge that conflicts and for a merge asked to wait while one is already scheduled, which stands, and names the cause in human text alone, and an archived repository is forgeapi.CodeRepoArchived. That is a permanent refusal whose remedy is an operator unarchiving the repository, never retried and never reported as a conflict, because no rebase and no re-read reaches that state. A strategy outside the family's own set is forgeapi.CodeStrategyNotAllowed before any request; the route's own 405 is forgeapi.CodeNotMergeable, because this product answers it for a disallowed merge style and for a pull request not yet mergeable alike.

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 REST call, the same pull-request read Client.ReadPR makes without the folded status that read adds, and the record carries the merged state and the pull request's own page. That folded status is what Client.ReadPR is for, and it is the call a caller wanting the check verdict makes on the same pull request; this read returns no checks and pays for none. Queue is forgeapi.QueueNone always: this family has no queue and no train, so the neutral member is the answer rather than a field omitted, which is what lets a caller written against another family read this one unchanged.

func (*Client) PoolOf

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

PoolOf is the pool the operation req belongs to last drew on, which on this family is always empty, the whole service: Forgejo reports its one figure under no pool name and Gitea reports none. 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. A forgeapi.Issue carries no successor, so a repository that moved answers forgeapi.CodeRepoRefStale carrying it.

func (*Client) ReadPR

ReadPR implements forgeapi.PullRequests: the record, its COMPLETE status fold up to forgeapi.Budget.StatusPages pages outside the per-interval cap, since this call is priced per call, and one page of its reviews unless forgeapi.WithReviews is false, which answers both review counts forgeapi.CountUnknown. A fold that reaches the bound answers forgeapi.CheckUnknown with forgeapi.PartialPaginationCap. Absence answers forgeapi.CodeRepoOrPRNotVisible always: one REST status cannot tell a missing pull request from an invisible repository, and a further read would break the price. A moved repository answers forgeapi.CodeRepoRefStale carrying the successor.

func (*Client) RemoveLabels

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

RemoveLabels implements forgeapi.Labels. The item's own label read names every label it carries, an organization's included, so only those are removed. Gitea's route takes the label's id, so every carried label of a name is removed, a repository's and an organization's of one name both. Forgejo's takes a name or an id, resolving a name to the repository's label before the organization's and an id to a repository label only, so it is sent the name, which an id could be mistaken for (routers/api/v1/repo/issue_label.go DeleteIssueLabel on each). A label or item gone since the read answers 404 or 422 there, and the item carries no label.

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. forgeapi.RepoAffordances.MergeTrain is forgeapi.SupportNo on every repository of this family, which has neither a merge queue nor a merge train, and its evidence source is forgeapi.EvidenceVersion rather than the response body the other values come from: no field of the repository record answers it, and what does is the product the version body identified.

A forgeapi.RepoAffordances carries no successor, so a repository that moved answers forgeapi.CodeRepoRefStale carrying it.

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. A missing verb is a capability rather than an unimplemented role, because one package serves every version of both products.

func (*Client) RerunFailedRun

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

RerunFailedRun implements forgeapi.Checks. It is gated on forgeapi.CapRerunChecks as Client.RerunFailedChecks is, and posts to the route detection held: the failed-jobs re-run, or Forgejo's whole-run re-run, which starts any finished run again, so there the run is read first and one [Client.rerunnable] does not hold is refused.

func (*Client) Whoami

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

Whoami implements forgeapi.Identity.

Jump to

Keyboard shortcuts

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