gtpr

Documentation

Overview

Package gtpr fetches the lockfile changes of a Gitea / Forgejo pull request (or a single commit) via the REST API, so it can be vetted without cloning the repository. Works with codeberg.org, gitea.com, and any self-hosted Gitea or Forgejo instance — the host comes from the URL.

Index

• Variables
• func Fetch(ref Ref, isLockfile func(path string) bool) (*ghpr.Result, error)
• func FetchCommit(ref CommitRef, isLockfile func(path string) bool) (*ghpr.Result, error)
• func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*ghpr.Result, error)
• func HasToken() bool
• func IsGiteaHost(host string) bool
• func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)
• type CmpRef
  • func ParseCompare(s string) (CmpRef, bool)
  • func (r CmpRef) String() string
• type CommitRef
  • func ParseCommit(s string) (CommitRef, bool)
  • func (r CommitRef) String() string
• type QueueItem
  • func ListQueue(host, scope string, authors []string, limit int) ([]QueueItem, string, error)
• type Ref
  • func Parse(s string) (Ref, bool)
  • func (r Ref) String() string

Variables

var DefaultQueueAuthors = []string{"renovate-bot", "dependabot"}

DefaultQueueAuthors are the bot usernames queried when the user doesn't pass -author. Gitea/Forgejo have no canonical bot account — self-hosted Renovate runs under whatever user it's given (Forgejo's own is viceice-bot) — so these are just the common conventions; custom bots need an explicit -author.

Functions

func Fetch

func Fetch(ref Ref, isLockfile func(path string) bool) (*ghpr.Result, error)

Fetch downloads the PR metadata and the before/after contents of every changed file isLockfile accepts. Both sides are read from the base repository: Gitea keeps PR head commits reachable there even for fork PRs. Authenticates with GITEA_TOKEN / FORGEJO_TOKEN / CODEBERG_TOKEN when set; works unauthenticated on public repositories.

func FetchCommit

func FetchCommit(ref CommitRef, isLockfile func(path string) bool) (*ghpr.Result, error)

FetchCommit downloads the file changes a single commit makes relative to its first parent, and returns the before/after contents of every changed file isLockfile accepts.

func FetchCompare

func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*ghpr.Result, error)

FetchCompare downloads the file changes between two revisions via the Gitea compare API and returns the before/after contents of every changed file isLockfile accepts. The changed-file set is the union of the files touched by the commits on the head side (three-dot semantics, like a PR diff); contents are read at BASE and HEAD themselves, so each file's before/after is the direct diff of the two revisions.

func HasToken

func HasToken() bool

HasToken reports whether a Gitea/Forgejo API token is configured in the environment.

func IsGiteaHost

func IsGiteaHost(host string) bool

IsGiteaHost reports whether host serves a Gitea/Forgejo API. Known hosts and obvious names ("gitea.*", "forgejo.*", "gitlab.*") are answered without a network call; anything else is probed with one anonymous GET of /api/v1/version — Gitea and Forgejo answer it (or demand auth for it), while GitLab has no /api/v1 routes at all.

func PostComment

func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)

PostComment creates — or, if a lockvet comment already exists, updates — the report comment on a Gitea/Forgejo pull request. Returns the comment's URL and whether an existing comment was updated. Requires GITEA_TOKEN / FORGEJO_TOKEN / CODEBERG_TOKEN with write access.

Types

type CmpRef

type CmpRef struct {
	Host  string // e.g. "codeberg.org"
	Owner string
	Repo  string
	Base  string
	Head  string
}

CmpRef identifies a comparison between two revisions of a repository on a Gitea/Forgejo host.

func ParseCompare

func ParseCompare(s string) (CmpRef, bool)

ParseCompare recognises a Gitea/Forgejo compare URL:

https://codeberg.org/OWNER/REPO/compare/BASE...HEAD

BASE and HEAD may be branches (slashes ok), tags, or SHAs. A trailing .diff / .patch, ?query, or #fragment is ignored.

func (CmpRef) String

func (r CmpRef) String() string

type CommitRef

type CommitRef struct {
	Host  string
	Owner string
	Repo  string
	SHA   string
}

CommitRef identifies a single commit on a Gitea/Forgejo host.

func ParseCommit

func ParseCommit(s string) (CommitRef, bool)

ParseCommit recognises a Gitea/Forgejo commit URL:

https://codeberg.org/OWNER/REPO/commit/SHA

github.com is excluded (handled by the GitHub path), as are gitlab.com and bitbucket.org, whose commit URLs use different shapes anyway.

func (CommitRef) String

func (r CommitRef) String() string

type QueueItem

type QueueItem struct {
	Ref     Ref
	Title   string
	Author  string
	URL     string // html_url
	Updated time.Time
}

QueueItem is one open dependency-update pull request found by ListQueue.

func ListQueue

func ListQueue(host, scope string, authors []string, limit int) ([]QueueItem, string, error)

ListQueue finds open pull requests by the given authors in scope on a Gitea/Forgejo host. Scope is "owner" (user or org; all its repos) or "owner/repo". Authors may be empty to match every open PR. Results are most-recently-updated first, capped at limit. The returned string describes the scope (e.g. "owner:forgejo @ codeberg.org") for display.

Owner scope uses the instance-wide issue search endpoint, which cannot filter by author server-side, so up to 10×50 recently-updated open PRs are scanned client-side. Repo scope filters server-side (created_by), one request per author.

type Ref

type Ref struct {
	Host  string // e.g. "codeberg.org"
	Owner string
	Repo  string
	Index int
}

Ref identifies a pull request on a Gitea/Forgejo host.

func Parse

func Parse(s string) (Ref, bool)

Parse recognises a Gitea/Forgejo pull request URL:

https://codeberg.org/OWNER/REPO/pulls/123   (any Gitea/Forgejo host)

func (Ref) String

func (r Ref) String() string