Pull requests, reviews and bounded merges

The shared interface supports same-repository PR creation, comparisons, human review, reviewer requests and available authoring controls. Private pending inline drafts and broader portable review flows have their own qualified contracts. Native adapters are bounded and do not imply complete parity.

Native merge slice

A same-repository merge commit is supported when base is already an ancestor of head. Golf builds and pushes the commit through its authorized reservation/journal and verifies the resulting ref/commit. The retained hosted proof passed independent fetch and git fsck --strict.

Squash, diverged branches, forks, drafts and locked targets are refused. This is not complete protected merge, a merge queue or automatic production delivery. See previews and merge limits.

Detailed portable read contract

The following source/pagination details retain the earlier portable-provider qualification; historical provider behavior is not automatically a new Forgejo or native-hosted proof.

Access and navigation

A personal token needs read:user plus read:repository, together with the user's underlying repository permissions. Pull-request and review browsing does not require read:issue; the Issues tab has that separate scope. The existing browser OAuth scope set already covers these reads, so this increment does not request an additional OAuth grant.

Detail links use /repositories/OWNER/REPOSITORY?view=pulls&pull=NUMBER; state=closed or state=all preserves the list filter. A pull number must be a canonical positive integer from 1 through 2147483647. Leading zeroes, signs, decimal fractions and exponent notation are rejected. Changing repository tabs clears the selected pull number. Direct links, reload and browser history retain the selected detail.

Private content is held only in the browser's cancellable query cache. Refresh revalidates access; denial hides prior results rather than retaining stale details or reviews. Session expiry, current-session revocation and sign-out clear private queries. Body and review text is escaped plain text, not rendered Markdown or executable HTML. External forge links are limited to HTTP(S) URLs without embedded credentials.

Read the source metadata carefully

Base and head metadata preserve the provider's repository ID, label, ref and exact commit ID. IDs remain strings. An absent repository ID is shown as unavailable; it is not replaced with another repository's identity.

Retained PR snapshot means the provider returned a retained PR representation. Native list results use that representation even when their displayed ref still names a branch. Detail may instead observe the source branch, but Provider observation does not promise freshness, reserve that branch or prove it still exists at a later operation.

After a source branch is deleted, detail can still contain its last commit under refs/pull/NUMBER/head. That snapshot is useful for reading the proposal; it is not a live source branch. This distinction is especially important for private-fork proposals, where a caller may read the base PR without direct access to the fork repository.

Interpret native reviews

Review records preserve their ID, available author, plain-text body, state, reviewed commit, submission/update times and the native stale, dismissed and official flags. Deleted or unavailable authors are labeled accordingly. An Approved (native forge) record is not a computed eligible Golf approval; an unmarked stale flag is not proof that its commit or policy remains current.

Use Load more reviews while a continuation is available. Forgejo can filter a pending review after pagination, leaving an empty page with a valid next page. Follow page.nextPage, not array length. The browser deduplicates loaded IDs and hides earlier rows if a later page is denied. These collections are not snapshots across concurrent provider changes.

API and CLI

The generated RepositoryService exposes ListPullRequests, GetPullRequest and ListPullRequestReviews. See the API reference for message and pagination details. The CLI uses the same user-scoped procedures:

./bin/golf pr list owner/repository --state open --page 1 --limit 20
./bin/golf pr view owner/repository 12
./bin/golf pr reviews owner/repository 12 --page 1 --limit 20

Supply the token through GOLF_FORGE_TOKEN or the global --token-stdin option. Each command opens and closes its own temporary Golf session, returning one page as JSON without storing credentials.

Full protected integration remains unqualified. Current portable authoring and bounded native review adapters are separate from a trusted protected-publication gate. See current status and protected-write qualification for that separate gate.

Owner-issued Golf API credentials also support these reads through GOLF_API_TOKEN or --api-token-stdin, without temporary sign-in/sign-out. The PAT-mode lifecycle above remains available. Native scopes and permissions still govern access.