Documentation
¶
Overview ¶
Package forgejo provides a Forgejo API client for pull request lifecycle management.
The package handles:
- Creating and fetching pull requests with assignees, reviewers, and labels
- Waiting for Forgejo Actions / commit-status CI completion with real-time visualization
- Merging pull requests (merge or squash strategies, with automatic branch deletion)
- Label retrieval for interactive selection
Authentication requires a FORGEJO_TOKEN environment variable containing a personal access token with the required repository scopes.
Usage:
client, err := forgejo.NewClient("https://forgejo.example.com")
client.SetLogger(logger)
client.SetRepositoryFromURL("https://forgejo.example.com/owner/repo.git")
labels, _ := client.ListLabels()
pr, _ := client.CreatePullRequest("feature", "main", "Title", "Body", "assignee", "reviewer", nil)
Thread Safety: Client is not safe for concurrent use. The pipeline waiting methods use internal goroutines but the Client itself should be used from a single goroutine.
Index ¶
- Variables
- type APIClient
- type Client
- func (c *Client) CreatePullRequest(head, base, title, body, assignee, reviewer string, labels []string) (*gitea.PullRequest, error)
- func (c *Client) GetPullRequestByBranch(head, base string) (*gitea.PullRequest, error)
- func (c *Client) ListLabels() ([]Label, error)
- func (c *Client) MergePullRequest(index int64, squash bool, commitTitle string) error
- func (c *Client) SetLogger(logger *bullets.Logger)
- func (c *Client) SetRepositoryFromURL(url string) error
- func (c *Client) WaitForPipeline(timeout time.Duration) (string, error)
- type DisplayRenderer
- type Label
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTokenRequired is returned when FORGEJO_TOKEN environment variable is missing. ErrTokenRequired = errTokenRequired // ErrInvalidURLFormat is returned when the Forgejo URL format is invalid. ErrInvalidURLFormat = errInvalidURLFormat // ErrWorkflowTimeout is returned when waiting for pipeline completion times out. ErrWorkflowTimeout = errWorkflowTimeout // ErrPRNotFound is returned when no pull request is found for the branch. ErrPRNotFound = errPRNotFound // ErrPRAlreadyExists is returned when a pull request already exists for the branch. ErrPRAlreadyExists = errPRAlreadyExists )
Error definitions for Forgejo API operations.
Functions ¶
This section is empty.
Types ¶
type APIClient ¶
type APIClient interface {
// SetRepositoryFromURL configures the repository from a git remote URL.
// Supports both HTTPS and SSH formats.
SetRepositoryFromURL(url string) error
// ListLabels returns all labels available in the repository.
ListLabels() ([]Label, error)
// CreatePullRequest creates a new pull request with the specified parameters.
// Returns the created pull request or an error if creation fails.
CreatePullRequest(
head, base, title, body, assignee, reviewer string,
labels []string,
) (*gitea.PullRequest, error)
// GetPullRequestByBranch fetches an existing pull request by head and base branches.
// Returns ErrPRNotFound if no matching pull request exists.
GetPullRequestByBranch(head, base string) (*gitea.PullRequest, error)
// WaitForPipeline waits for all commit statuses to complete for the pull request.
// Returns the overall result ("success", "failure", "error") or an error on timeout.
WaitForPipeline(timeout time.Duration) (string, error)
// MergePullRequest merges a pull request using the specified strategy.
// index is the PR index (number). squash controls merge style.
// commitTitle is used as the merge commit message.
MergePullRequest(index int64, squash bool, commitTitle string) error
}
APIClient defines the interface for Forgejo API operations. This interface enables dependency injection and facilitates black box testing by allowing mock implementations to replace the actual Forgejo API client.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a Forgejo API client wrapper that manages pull request lifecycle operations. It stores internal state (owner, repo, prIndex, prSHA) that is set by methods like Client.SetRepositoryFromURL and Client.CreatePullRequest.
Not safe for concurrent use.
func NewClient ¶
NewClient creates a new Forgejo client authenticated via the FORGEJO_TOKEN environment variable.
Parameters:
- baseURL: the base URL of the Forgejo instance (e.g. "https://forgejo.example.com")
Returns ErrTokenRequired if FORGEJO_TOKEN is not set.
func (*Client) CreatePullRequest ¶
func (c *Client) CreatePullRequest( head, base, title, body, assignee, reviewer string, labels []string, ) (*gitea.PullRequest, error)
CreatePullRequest creates a new pull request with assignee, reviewer, and labels. Label names are resolved to IDs via the repository's label list; names with no match are silently skipped.
Parameters:
- head: the source branch name
- base: the target branch (e.g., "main")
- title: PR title (must not be empty)
- body: PR description
- assignee: Forgejo username to assign (empty string is skipped)
- reviewer: Forgejo username to request review from (empty or same as assignee is skipped)
- labels: label names to apply (may be nil)
Returns ErrPRAlreadyExists if a PR already exists for the same branches. Stores the PR index and head SHA internally for use by Client.WaitForPipeline.
func (*Client) GetPullRequestByBranch ¶
func (c *Client) GetPullRequestByBranch(head, base string) (*gitea.PullRequest, error)
GetPullRequestByBranch fetches an existing open pull request by head and base branches. Only the first matching PR is returned. Stores the PR index and SHA internally.
Returns ErrPRNotFound if no open PR matches the given branches.
func (*Client) ListLabels ¶
ListLabels returns all labels for the repository. Client.SetRepositoryFromURL must be called before this method.
Returns an empty slice if no labels are configured.
func (*Client) MergePullRequest ¶
MergePullRequest merges a pull request, automatically deleting the head branch.
Parameters:
- index: the pull request index (number)
- squash: if true, uses squash merge; otherwise standard merge
- commitTitle: used as the merge commit message
func (*Client) SetRepositoryFromURL ¶
SetRepositoryFromURL sets the repository from a git remote URL. Supports both HTTPS and SSH URL formats:
- https://forgejo.example.com/owner/repo.git
- git@forgejo.example.com:owner/repo.git
Returns ErrInvalidURLFormat if the URL cannot be parsed into owner/repo. Returns a wrapped error if the repository does not exist or the API call fails.
func (*Client) WaitForPipeline ¶
WaitForPipeline waits for all commit statuses to complete for the pull request SHA. It polls at 5-second intervals and displays real-time per-context progress with animated spinners.
If no commit statuses are configured after a brief grace period, it returns "success" immediately (treating "no CI" as success, exactly like a repo with no workflows).
Parameters:
- timeout: maximum wait duration (typically 1m to 8h)
Returns the overall result ("success", "failure", or "error"). Returns ErrWorkflowTimeout if the timeout is exceeded.
A pull request must have been created or fetched before calling this method.
type DisplayRenderer ¶
type DisplayRenderer interface {
// Info logs an informational message.
Info(message string)
// Debug logs a debug message.
Debug(message string)
// Error logs an error message.
Error(message string)
// Success logs a success message.
Success(message string)
// InfoHandle creates an updatable handle for an info message.
InfoHandle(message string) *bullets.BulletHandle
// SpinnerCircle creates an animated spinner with the given message.
SpinnerCircle(ctx context.Context, message string) *bullets.Spinner
// IncreasePadding increases the indentation level for nested output.
IncreasePadding()
// DecreasePadding decreases the indentation level for nested output.
DecreasePadding()
}
DisplayRenderer defines the interface for UI rendering operations. This interface abstracts the bullets.Logger and bullets.UpdatableLogger functionality to enable testing of display logic without actual terminal output.
Source Files