Documentation
¶
Overview ¶
Package provider defines the interface for Git forge providers.
This package contains the common interface and types used by all Git forge implementations (GitHub, GitLab, Gitea).
Interface ¶
The Provider interface defines methods for:
- Repository listing (organization and user)
- Single repository retrieval
- Organization listing
- Token validation
- Rate limit checking
Types ¶
- Repository: Common repository representation
- Organization: Common organization representation
- RateLimit: Rate limit status
Implementations ¶
See the github, gitlab, and gitea packages for concrete implementations.
Index ¶
- Variables
- func ClassifyTokenValidationError(providerName string, status int, headers http.Header, cause error) error
- type CreatePullRequestInput
- type ForgeRemote
- type ListOptions
- type Organization
- type Provider
- type ProviderWithAuth
- type PullRequest
- type PullRequester
- type RateLimit
- type Repository
- type SyncAction
- type SyncOptions
- type SyncResult
- type Syncer
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTokenForbidden indicates that the provider rejected the credentials. ErrTokenForbidden = errors.New("token validation forbidden") // ErrTokenValidationRateLimited indicates that validation was rejected by a // provider rate limit. ErrTokenValidationRateLimited = errors.New("token validation rate limited") // ErrTokenValidationUnreachable indicates that the validation endpoint could // not be reached (for example, a transport or DNS failure). ErrTokenValidationUnreachable = errors.New("token validation endpoint unreachable") // ErrTokenValidationAPI indicates an API response that was neither an // authentication rejection nor a rate-limit response. ErrTokenValidationAPI = errors.New("token validation API error") // ErrTokenValidationCanceled indicates that the caller canceled validation. ErrTokenValidationCanceled = errors.New("token validation canceled") )
var ErrPullRequestNotFound = errors.New("pull request not found")
ErrPullRequestNotFound means no open PR/MR matched the head/base pair.
Functions ¶
func ClassifyTokenValidationError ¶
func ClassifyTokenValidationError(providerName string, status int, headers http.Header, cause error) error
ClassifyTokenValidationError wraps a provider validation failure with a stable, provider-independent sentinel. The response status and headers are optional when the request failed before an HTTP response was received.
A 403 is treated as a credential rejection unless the provider explicitly reports that its rate limit is exhausted. 401 remains the caller's responsibility because providers historically return (false, nil) for it.
Types ¶
type CreatePullRequestInput ¶
type CreatePullRequestInput struct {
Owner string
Repo string
Title string
Body string
Head string
Base string
Draft bool
Reviewers []string
Labels []string
}
CreatePullRequestInput is the minimum create surface.
type ForgeRemote ¶
type ForgeRemote struct {
Provider string // github, gitlab, gitea, or empty if unknown
Host string
Owner string
Repo string
BaseURL string // empty for github.com / gitlab.com defaults
}
ForgeRemote is a parsed git remote pointing at a forge.
func ParseForgeRemote ¶
func ParseForgeRemote(raw string) (ForgeRemote, error)
ParseForgeRemote extracts provider, owner, and repo from a git remote URL.
type ListOptions ¶
ListOptions common pagination options.
type Organization ¶
Organization represents an organization or group from any Git platform.
type Provider ¶
type Provider interface {
// Name returns the provider name (github, gitlab, gitea)
Name() string
// ListOrganizationRepos lists all repositories in an organization/group
ListOrganizationRepos(ctx context.Context, org string) ([]*Repository, error)
// ListUserRepos lists all repositories for a user
ListUserRepos(ctx context.Context, user string) ([]*Repository, error)
// GetRepository gets a single repository
GetRepository(ctx context.Context, owner, repo string) (*Repository, error)
// ListOrganizations lists organizations the authenticated user belongs to
ListOrganizations(ctx context.Context) ([]*Organization, error)
// GetRateLimit returns current rate limit status
GetRateLimit(ctx context.Context) (*RateLimit, error)
}
Provider defines the interface for Git platform providers.
type ProviderWithAuth ¶
type ProviderWithAuth interface {
Provider
// SetToken sets the authentication token
SetToken(token string) error
// ValidateToken validates the current token
ValidateToken(ctx context.Context) (bool, error)
}
ProviderWithAuth extends Provider with authentication capabilities.
type PullRequest ¶
type PullRequest struct {
Number int
URL string
Title string
Head string
Base string
Draft bool
Kind string // "pull" or "merge_request"
}
PullRequest is a forge-neutral PR or merge request.
type PullRequester ¶
type PullRequester interface {
CreatePullRequest(ctx context.Context, in CreatePullRequestInput) (*PullRequest, error)
FindPullRequest(ctx context.Context, owner, repo, head, base string) (*PullRequest, error)
}
PullRequester creates and looks up pull requests / merge requests. It is a sibling of Provider so listing-only mocks stay valid.
type Repository ¶
type Repository struct {
Name string
FullName string
CloneURL string
SSHURL string
HTMLURL string
Description string
DefaultBranch string
Private bool
Archived bool
Fork bool
Disabled bool
Language string
Size int
Stars int
Topics []string
Visibility string
CreatedAt time.Time
UpdatedAt time.Time
PushedAt time.Time
}
Repository represents a repository from any Git platform.
type SyncAction ¶
type SyncAction string
SyncAction represents what action was taken during sync.
const ( ActionCloned SyncAction = "cloned" ActionUpdated SyncAction = "updated" ActionSkipped SyncAction = "skipped" ActionFailed SyncAction = "failed" )
SyncAction values describe the outcome of a repository sync operation.
type SyncOptions ¶
type SyncOptions struct {
TargetPath string
Parallel int
IncludeArchived bool
IncludeForks bool
IncludePrivate bool
DryRun bool
}
SyncOptions configures repository synchronization.
type SyncResult ¶
type SyncResult struct {
Repository *Repository
Action SyncAction
Error error
}
SyncResult represents the result of syncing a single repository.
type Syncer ¶
type Syncer interface {
// SyncOrganization syncs all repositories from an organization
SyncOrganization(ctx context.Context, provider Provider, org string, opts SyncOptions) ([]SyncResult, error)
}
Syncer handles repository synchronization operations.