Documentation
¶
Overview ¶
Package pr provides pull request operations for GitHub and GitLab.
Core types:
- Provider: Interface for creating and managing pull requests
- Options: Configuration for creating a pull request
- PullRequest: Represents a created pull request with URL and number
- Builder: Fluent builder for constructing PR descriptions
Implementations:
- GitHubProvider: GitHub PR provider using go-github
- GitLabProvider: GitLab MR provider using go-gitlab
Example usage:
provider, _ := pr.NewGitHubProvider(token, "owner", "repo")
pull, err := provider.CreatePR(ctx, pr.Options{
Title: "Add feature",
Body: "Description",
Base: "main",
Head: "feature/my-branch",
})
Index ¶
- Variables
- func DetectProvider(remoteURL string) (string, error)
- func ParseRepoFromURL(remoteURL string) (owner, repo string, err error)
- type Builder
- func (b *Builder) AsDraft() *Builder
- func (b *Builder) Build() Options
- func (b *Builder) WithAssignees(assignees ...string) *Builder
- func (b *Builder) WithBase(base string) *Builder
- func (b *Builder) WithBody(body string) *Builder
- func (b *Builder) WithHead(head string) *Builder
- func (b *Builder) WithLabels(labels ...string) *Builder
- func (b *Builder) WithMetadata(key, value string) *Builder
- func (b *Builder) WithMilestone(milestone string) *Builder
- func (b *Builder) WithReviewers(reviewers ...string) *Builder
- func (b *Builder) WithSummary(summary string, changes []string, testPlan string) *Builder
- func (b *Builder) WithTicket(ticketID string) *Builder
- type Filter
- type GitHubProvider
- func (p *GitHubProvider) AddComment(ctx context.Context, id int, body string) error
- func (p *GitHubProvider) CreatePR(ctx context.Context, opts Options) (*PullRequest, error)
- func (p *GitHubProvider) GetPR(ctx context.Context, id int) (*PullRequest, error)
- func (p *GitHubProvider) ListPRs(ctx context.Context, filter Filter) ([]*PullRequest, error)
- func (p *GitHubProvider) MergePR(ctx context.Context, id int, opts MergeOptions) error
- func (p *GitHubProvider) RequestReview(ctx context.Context, id int, reviewers []string) error
- func (p *GitHubProvider) UpdatePR(ctx context.Context, id int, opts UpdateOptions) (*PullRequest, error)
- type GitLabProvider
- func (p *GitLabProvider) AddComment(ctx context.Context, id int, body string) error
- func (p *GitLabProvider) CreatePR(ctx context.Context, opts Options) (*PullRequest, error)
- func (p *GitLabProvider) GetPR(ctx context.Context, id int) (*PullRequest, error)
- func (p *GitLabProvider) ListPRs(ctx context.Context, filter Filter) ([]*PullRequest, error)
- func (p *GitLabProvider) MergePR(ctx context.Context, id int, opts MergeOptions) error
- func (p *GitLabProvider) RequestReview(ctx context.Context, id int, reviewers []string) error
- func (p *GitLabProvider) UpdatePR(ctx context.Context, id int, opts UpdateOptions) (*PullRequest, error)
- type MergeMethod
- type MergeOptions
- type Options
- type Provider
- type PullRequest
- type State
- type UpdateOptions
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoProvider indicates no PR provider is configured. ErrNoProvider = errors.New("no PR provider configured") // ErrUnknownProvider indicates the git remote uses an unknown provider. ErrUnknownProvider = errors.New("unknown git provider") // ErrExists indicates a PR already exists for the branch. ErrExists = errors.New("pull request already exists for this branch") // ErrNotFound indicates the PR does not exist. ErrNotFound = errors.New("pull request not found") // ErrClosed indicates the PR is closed. ErrClosed = errors.New("pull request is closed") // ErrMerged indicates the PR is already merged. ErrMerged = errors.New("pull request is already merged") // ErrBranchNotPushed indicates the branch has not been pushed to remote. ErrBranchNotPushed = errors.New("branch not pushed to remote") // ErrNoChanges indicates there are no changes between branches. ErrNoChanges = errors.New("no changes between branches") // ErrMergeConflict indicates a merge conflict occurred. ErrMergeConflict = errors.New("merge conflict") )
PR provider errors
Functions ¶
func DetectProvider ¶
DetectProvider attempts to detect the PR provider from a remote URL.
func ParseRepoFromURL ¶
ParseRepoFromURL extracts owner and repo from a git remote URL.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder helps construct PR options using a fluent interface.
func NewBuilder ¶
NewBuilder creates a new PR builder with the given title.
func (*Builder) WithAssignees ¶
WithAssignees adds assignees.
func (*Builder) WithLabels ¶
WithLabels adds labels.
func (*Builder) WithMetadata ¶
WithMetadata adds custom metadata.
func (*Builder) WithMilestone ¶
WithMilestone sets the milestone.
func (*Builder) WithReviewers ¶
WithReviewers adds reviewers.
func (*Builder) WithSummary ¶
WithSummary creates a formatted body with summary, changes, and test plan.
func (*Builder) WithTicket ¶
WithTicket adds a ticket reference to the title. Example: "Add feature" -> "[TK-421] Add feature"
type Filter ¶
type Filter struct {
State State // Filter by state (empty = all)
Base string // Filter by base branch
Head string // Filter by head branch
Author string // Filter by author username
Labels []string // Filter by labels (all must match)
Sort string // Sort field (created, updated)
Direction string // Sort direction (asc, desc)
Limit int // Maximum number to return (0 = default)
}
Filter configures pull request listing.
type GitHubProvider ¶
type GitHubProvider struct {
// contains filtered or unexported fields
}
GitHubProvider implements Provider for GitHub repositories.
func NewGitHubProvider ¶
func NewGitHubProvider(token, owner, repo string) (*GitHubProvider, error)
NewGitHubProvider creates a new GitHub provider. token is a personal access token or GitHub App token. owner and repo identify the repository (e.g., "anthropic", "devflow").
func NewGitHubProviderFromURL ¶
func NewGitHubProviderFromURL(token, remoteURL string) (*GitHubProvider, error)
NewGitHubProviderFromURL creates a GitHub provider from a remote URL. Example: "https://github.com/randalmurphal/devflow.git"
func (*GitHubProvider) AddComment ¶
AddComment adds a comment to a pull request.
func (*GitHubProvider) CreatePR ¶
func (p *GitHubProvider) CreatePR(ctx context.Context, opts Options) (*PullRequest, error)
CreatePR creates a new pull request.
func (*GitHubProvider) GetPR ¶
func (p *GitHubProvider) GetPR(ctx context.Context, id int) (*PullRequest, error)
GetPR retrieves a pull request by number.
func (*GitHubProvider) ListPRs ¶
func (p *GitHubProvider) ListPRs(ctx context.Context, filter Filter) ([]*PullRequest, error)
ListPRs lists pull requests matching the filter.
func (*GitHubProvider) MergePR ¶
func (p *GitHubProvider) MergePR(ctx context.Context, id int, opts MergeOptions) error
MergePR merges a pull request.
func (*GitHubProvider) RequestReview ¶
RequestReview requests review from the specified users.
func (*GitHubProvider) UpdatePR ¶
func (p *GitHubProvider) UpdatePR(ctx context.Context, id int, opts UpdateOptions) (*PullRequest, error)
UpdatePR updates an existing pull request.
type GitLabProvider ¶
type GitLabProvider struct {
// contains filtered or unexported fields
}
GitLabProvider implements Provider for GitLab repositories.
func NewGitLabProvider ¶
func NewGitLabProvider(token, baseURL, projectID string) (*GitLabProvider, error)
NewGitLabProvider creates a new GitLab provider. token is a personal access token. baseURL is the GitLab instance URL (empty for gitlab.com). projectID can be numeric ID or "namespace/project" path.
func NewGitLabProviderFromURL ¶
func NewGitLabProviderFromURL(token, remoteURL string) (*GitLabProvider, error)
NewGitLabProviderFromURL creates a GitLab provider from a remote URL. Example: "https://gitlab.com/namespace/project.git"
func (*GitLabProvider) AddComment ¶
AddComment adds a note to a merge request.
func (*GitLabProvider) CreatePR ¶
func (p *GitLabProvider) CreatePR(ctx context.Context, opts Options) (*PullRequest, error)
CreatePR creates a new merge request.
func (*GitLabProvider) GetPR ¶
func (p *GitLabProvider) GetPR(ctx context.Context, id int) (*PullRequest, error)
GetPR retrieves a merge request by IID.
func (*GitLabProvider) ListPRs ¶
func (p *GitLabProvider) ListPRs(ctx context.Context, filter Filter) ([]*PullRequest, error)
ListPRs lists merge requests matching the filter.
func (*GitLabProvider) MergePR ¶
func (p *GitLabProvider) MergePR(ctx context.Context, id int, opts MergeOptions) error
MergePR merges a merge request.
func (*GitLabProvider) RequestReview ¶
RequestReview requests review from the specified users. Note: GitLab uses reviewer IDs, so usernames should be numeric IDs.
func (*GitLabProvider) UpdatePR ¶
func (p *GitLabProvider) UpdatePR(ctx context.Context, id int, opts UpdateOptions) (*PullRequest, error)
UpdatePR updates an existing merge request.
type MergeMethod ¶
type MergeMethod string
MergeMethod specifies how to merge a pull request.
const ( MergeMethodMerge MergeMethod = "merge" MergeMethodSquash MergeMethod = "squash" MergeMethodRebase MergeMethod = "rebase" )
type MergeOptions ¶
type MergeOptions struct {
Method MergeMethod // Merge method (merge, squash, rebase)
CommitTitle string // Custom commit title (for squash/merge)
CommitMessage string // Custom commit message (for squash/merge)
SHA string // Expected HEAD SHA (for optimistic locking)
DeleteBranch bool // Delete source branch after merge
}
MergeOptions configures pull request merging.
type Options ¶
type Options struct {
Title string // PR title (required)
Body string // PR description (markdown)
Base string // Target branch (default: "main")
Head string // Source branch (auto-detected if empty)
Labels []string // Labels to apply
Reviewers []string // Reviewer usernames
Assignees []string // Assignee usernames
Draft bool // Create as draft
Milestone string // Milestone name or ID
Metadata map[string]string // Additional metadata
}
Options configures pull request creation.
type Provider ¶
type Provider interface {
// CreatePR creates a new pull request.
CreatePR(ctx context.Context, opts Options) (*PullRequest, error)
// GetPR retrieves a pull request by ID.
GetPR(ctx context.Context, id int) (*PullRequest, error)
// UpdatePR updates an existing pull request.
UpdatePR(ctx context.Context, id int, opts UpdateOptions) (*PullRequest, error)
// MergePR merges a pull request.
MergePR(ctx context.Context, id int, opts MergeOptions) error
// AddComment adds a comment to a pull request.
AddComment(ctx context.Context, id int, body string) error
// RequestReview requests review from the specified users.
RequestReview(ctx context.Context, id int, reviewers []string) error
// ListPRs lists pull requests matching the filter.
ListPRs(ctx context.Context, filter Filter) ([]*PullRequest, error)
}
Provider is the interface for creating and managing pull requests. Implementations exist for GitHub and GitLab.
type PullRequest ¶
type PullRequest struct {
ID int // PR number/ID
URL string // Web URL
HTMLURL string // Full HTML URL
Title string // PR title
Body string // PR description
State State // Current state
Draft bool // Whether it's a draft
Head string // Source branch
Base string // Target branch
CreatedAt time.Time // Creation time
UpdatedAt time.Time // Last update time
MergedAt *time.Time // Merge time (nil if not merged)
MergedBy string // Username who merged
Commits int // Number of commits
Additions int // Lines added
Deletions int // Lines deleted
ChangedFiles int // Number of files changed
Labels []string // Applied labels
Reviewers []string // Requested reviewers
Assignees []string // Assigned users
}
PullRequest represents a created pull request.
type UpdateOptions ¶
type UpdateOptions struct {
Title *string // New title (nil = no change)
Body *string // New body (nil = no change)
Base *string // New base branch (nil = no change)
Labels []string // Labels to set (replaces existing)
Assignees []string // Assignees to set (replaces existing)
Draft *bool // Draft status (nil = no change)
}
UpdateOptions configures pull request updates.