forge

Documentation

Overview

Package forge is a minimal Forgejo (Gitea-compatible) API client covering exactly what the merge queue needs: discovering auto-merge PRs, driving the required status check, merging, and reading gate-CI results.

Index

• Variables
• type AutomergeState
• type BranchProtection
• type Client
  • func New(instanceURL, token string) *Client
  • func NewWithConfig(instanceURL, token string, cfg Config) (*Client, error)
  • func (c *Client) AutomergeScheduled(ctx context.Context, owner, repo string, index int) (bool, error)
  • func (c *Client) AutomergeState(ctx context.Context, owner, repo string, index int) (AutomergeState, error)
  • func (c *Client) CancelAutomerge(ctx context.Context, owner, repo string, index int) (bool, error)
  • func (c *Client) Comment(ctx context.Context, owner, repo string, index int, body string) error
  • func (c *Client) DeleteBranch(ctx context.Context, owner, repo, branch string) error
  • func (c *Client) EnsureBranchProtection(ctx context.Context, owner, repo, base, statusCtx, botUser string) (changed bool, err error)
  • func (c *Client) EnsureStagingBranchProtection(ctx context.Context, owner, repo, base, botUser string) (changed bool, err error)
  • func (c *Client) EnsureWebhook(ctx context.Context, owner, repo, targetURL, secret string) (changed bool, err error)
  • func (c *Client) GetPR(ctx context.Context, owner, repo string, index int) (PullRequest, error)
  • func (c *Client) LatestCommitStatus(ctx context.Context, owner, repo, sha, statusContext string) (CommitStatus, bool, error)
  • func (c *Client) ListOpenPRs(ctx context.Context, owner, repo, base string) ([]PullRequest, error)
  • func (c *Client) ReadFile(ctx context.Context, owner, repo, ref, path string) ([]byte, error)
  • func (c *Client) RunStatus(ctx context.Context, owner, repo, sha, branch string) (string, error)
  • func (c *Client) RunTargetURL(ctx context.Context, owner, repo, sha, branch string) (string, error)
  • func (c *Client) ScheduleAutomerge(ctx context.Context, owner, repo string, index int, style, headSHA string) (ScheduleAutomergeResult, error)
  • func (c *Client) SearchReposByTopic(ctx context.Context, topic string) ([]RepoRef, error)
  • func (c *Client) SetCommitStatus(ctx context.Context, ...) error
  • func (c *Client) UpsertComment(ctx context.Context, owner, repo string, index int, ...) error
• type CommitStatus
• type Config
  • func DefaultConfig() Config
  • func (c Config) Validate() error
• type Hook
• type IssueComment
• type PullRequest
• type RepoRef
• type ScheduleAutomergeResult
• type UnavailableError
  • func (e *UnavailableError) Error() string
  • func (e *UnavailableError) Unwrap() []error

Variables

var (
	ErrNotFound    = errors.New("forge: not found")
	ErrUnavailable = errors.New("forge: unavailable")
	ErrRateLimited = errors.New("forge: rate limited")
)

Types

type AutomergeState

type AutomergeState struct {
	Scheduled bool
	UpdatedAt time.Time
}

type BranchProtection

type BranchProtection struct {
	EnableStatusCheck       bool     `json:"enable_status_check"`
	StatusCheckContexts     []string `json:"status_check_contexts"`
	EnablePush              bool     `json:"enable_push"`
	EnablePushWhitelist     bool     `json:"enable_push_whitelist"`
	PushWhitelistUsernames  []string `json:"push_whitelist_usernames"`
	PushWhitelistTeams      []string `json:"push_whitelist_teams"`
	PushWhitelistDeployKeys bool     `json:"push_whitelist_deploy_keys"`
}

BranchProtection is the subset of a Forgejo branch-protection rule we manage.

type Client

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

func New

func New(instanceURL, token string) *Client

func NewWithConfig

func NewWithConfig(instanceURL, token string, cfg Config) (*Client, error)

NewWithConfig creates a client with cfg.

func (*Client) AutomergeScheduled

func (c *Client) AutomergeScheduled(ctx context.Context, owner, repo string, index int) (bool, error)

func (*Client) AutomergeState

func (c *Client) AutomergeState(ctx context.Context, owner, repo string, index int) (AutomergeState, error)

AutomergeState returns the latest scheduled-auto-merge transition recorded in the PR timeline. Forgejo does not expose the live state on the PR object.

func (*Client) CancelAutomerge

func (c *Client) CancelAutomerge(ctx context.Context, owner, repo string, index int) (bool, error)

CancelAutomerge reports whether a live scheduled merge was removed.

func (*Client) Comment

func (c *Client) Comment(ctx context.Context, owner, repo string, index int, body string) error

func (*Client) DeleteBranch

func (c *Client) DeleteBranch(ctx context.Context, owner, repo, branch string) error

DeleteBranch removes the named branch from the repository. A 404 response is treated as success (branch already deleted).

func (*Client) EnsureBranchProtection

func (c *Client) EnsureBranchProtection(ctx context.Context, owner, repo, base, statusCtx, botUser string) (changed bool, err error)

EnsureBranchProtection makes sure base requires statusCtx and that direct pushes remain restricted. shunt only pushes staging branches, so any legacy base-branch push grant for botUser is removed; other grants are preserved.

func (*Client) EnsureStagingBranchProtection

func (c *Client) EnsureStagingBranchProtection(ctx context.Context, owner, repo, base, botUser string) (changed bool, err error)

EnsureStagingBranchProtection makes sure only botUser may push shunt-owned staging branches for base.

func (*Client) EnsureWebhook

func (c *Client) EnsureWebhook(ctx context.Context, owner, repo, targetURL, secret string) (changed bool, err error)

EnsureWebhook makes sure the repository has one active shunt webhook pointing at targetURL. It only manages hooks with the same URL, so unrelated operator hooks are left alone.

func (*Client) GetPR

func (c *Client) GetPR(ctx context.Context, owner, repo string, index int) (PullRequest, error)

GetPR fetches a single pull request.

func (*Client) LatestCommitStatus

func (c *Client) LatestCommitStatus(ctx context.Context, owner, repo, sha, statusContext string) (CommitStatus, bool, error)

func (*Client) ListOpenPRs

func (c *Client) ListOpenPRs(ctx context.Context, owner, repo, base string) ([]PullRequest, error)

ListOpenPRs returns open PRs, optionally filtered to those targeting base.

func (*Client) ReadFile

func (c *Client) ReadFile(ctx context.Context, owner, repo, ref, path string) ([]byte, error)

func (*Client) RunStatus

func (c *Client) RunStatus(ctx context.Context, owner, repo, sha, branch string) (string, error)

RunStatus returns the aggregate gate workflow status for (sha, branch), or "" if no run exists yet. Prefer Forgejo's run-level status because dependent task rows are materialized lazily in multi-job workflows.

func (*Client) RunTargetURL

func (c *Client) RunTargetURL(ctx context.Context, owner, repo, sha, branch string) (string, error)

RunTargetURL returns a browser/debug URL for the newest matching staging run when Forgejo/Gitea exposes one. Not every version includes this in the task payload, so an empty URL is a valid "not available" result.

func (*Client) ScheduleAutomerge

func (c *Client) ScheduleAutomerge(ctx context.Context, owner, repo string, index int, style, headSHA string) (ScheduleAutomergeResult, error)

func (*Client) SearchReposByTopic

func (c *Client) SearchReposByTopic(ctx context.Context, topic string) ([]RepoRef, error)

SearchReposByTopic returns non-archived repos carrying the given topic.

func (*Client) SetCommitStatus

func (c *Client) SetCommitStatus(ctx context.Context, owner, repo, sha, statusContext, state, desc, targetURL string) error

func (*Client) UpsertComment

func (c *Client) UpsertComment(ctx context.Context, owner, repo string, index int, marker, botUser, body string) error

type CommitStatus

type CommitStatus struct {
	ID          int64     `json:"id"`
	Status      string    `json:"status"`
	Description string    `json:"description"`
	Context     string    `json:"context"`
	CreatedAt   time.Time `json:"created_at"`
}

type Config

type Config struct {
	RatePerSecond float64
	RateBurst     int
	RetryInitial  time.Duration
	RetryMax      time.Duration
	RetryAttempts int
	OutageInitial time.Duration
	OutageMax     time.Duration
}

Config controls process-wide request limiting and per-client resilience.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the forge client runtime defaults.

func (Config) Validate

func (c Config) Validate() error

Validate reports whether c has usable resilience settings.

type Hook

type Hook struct {
	ID     int64             `json:"id"`
	Type   string            `json:"type"`
	Config map[string]string `json:"config"`
	Events []string          `json:"events"`
	Active bool              `json:"active"`
}

Hook is the subset of a Forgejo/Gitea repository webhook we manage.

type IssueComment

type IssueComment struct {
	ID   int64  `json:"id"`
	Body string `json:"body"`
	User struct {
		UserName  string `json:"username"`
		Login     string `json:"login"`
		LoginName string `json:"login_name"`
	} `json:"user"`
}

type PullRequest

type PullRequest struct {
	Number int    `json:"number"`
	Title  string `json:"title"`
	State  string `json:"state"`
	Merged bool   `json:"merged"`
	Head   struct {
		Sha string `json:"sha"`
		Ref string `json:"ref"`
	} `json:"head"`
	Base struct {
		Ref string `json:"ref"`
	} `json:"base"`
}

type RepoRef

type RepoRef struct {
	Owner         string
	Name          string
	DefaultBranch string
}

RepoRef identifies a repository discovered for queue management.

type ScheduleAutomergeResult

type ScheduleAutomergeResult struct {
	// Eligible is true when Forgejo accepted the schedule request.
	// false means Forgejo rejected it (e.g., missing approvals, conflicts).
	Eligible bool
}

ScheduleAutomergeResult captures the outcome of a ScheduleAutomerge attempt.

type UnavailableError

type UnavailableError struct {
	Cause   error
	RetryAt time.Time
}

UnavailableError reports that the client is temporarily quieting requests after an outage or rate-limit response.

func (*UnavailableError) Error

func (e *UnavailableError) Error() string

func (*UnavailableError) Unwrap

func (e *UnavailableError) Unwrap() []error