forges

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2026 License: MIT Imports: 13 Imported by: 0

README

forges

Go module for fetching normalized repository metadata from git forges. Supports GitHub, GitLab, Gitea/Forgejo, and Bitbucket Cloud.

import "github.com/git-pkgs/forges"

Usage

client := forges.NewClient(
    forges.WithToken("github.com", os.Getenv("GITHUB_TOKEN")),
    forges.WithToken("gitlab.com", os.Getenv("GITLAB_TOKEN")),
)

repo, err := client.FetchRepository(ctx, "https://github.com/octocat/hello-world")
// repo.FullName == "octocat/hello-world"
// repo.License == "MIT"
// repo.StargazersCount == 12345

tags, err := client.FetchTags(ctx, "https://github.com/octocat/hello-world")
// tags[0].Name == "v1.0.0"
// tags[0].Commit == "abc123..."

Self-hosted instances can be registered with WithGitea or WithGitLab:

client := forges.NewClient(
    forges.WithGitea("gitea.example.com", token),
    forges.WithGitLab("gitlab.internal.dev", token),
)

Or detected automatically:

err := client.RegisterDomain(ctx, "git.example.com", token)

PURL support via the github.com/git-pkgs/purl module:

p, _ := purl.Parse("pkg:npm/lodash?repository_url=https://github.com/lodash/lodash")
repo, err := client.FetchRepositoryFromPURL(ctx, p)

Repository fields

FullName, Owner, Name, Description, Homepage, HTMLURL, Language, License (SPDX key), DefaultBranch, Fork, Archived, Private, MirrorURL, SourceName, Size, StargazersCount, ForksCount, OpenIssuesCount, SubscribersCount, HasIssues, PullRequestsEnabled, Topics, LogoURL, CreatedAt, UpdatedAt, PushedAt.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("repository not found")

ErrNotFound is returned when the requested repository does not exist.

View Source 
var ErrOwnerNotFound = errors.New("owner not found")

ErrOwnerNotFound is returned when the requested owner (org or user) does not exist.

Functions

func ParseRepoURL 

func ParseRepoURL(rawURL string) (domain, owner, repo string, err error)

ParseRepoURL extracts the domain, owner, and repo from a repository URL. It handles https://, schemeless, and git@host:owner/repo SSH URLs, and strips .git suffixes and extra path segments.

Types

type ArchivedFilter added in v0.1.1 

type ArchivedFilter int

ArchivedFilter controls how archived repositories are handled in list operations. 

const (
	ArchivedInclude ArchivedFilter = iota
	ArchivedExclude
	ArchivedOnly
)

type Client 

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

Client routes requests to the appropriate Forge based on the URL domain.

func NewClient 

func NewClient(opts ...Option) *Client

NewClient creates a Client with the default forge registrations and applies the given options.

func (*Client) FetchRepository 

func (c *Client) FetchRepository(ctx context.Context, repoURL string) (*Repository, error)

FetchRepository fetches normalized repository metadata from a URL string.

func (*Client) FetchRepositoryFromPURL 

func (c *Client) FetchRepositoryFromPURL(ctx context.Context, p *purl.PURL) (*Repository, error)

FetchRepositoryFromPURL fetches repository metadata using a PURL's repository_url qualifier.

func (*Client) FetchTags 

func (c *Client) FetchTags(ctx context.Context, repoURL string) ([]Tag, error)

FetchTags fetches git tags from a URL string.

func (*Client) FetchTagsFromPURL 

func (c *Client) FetchTagsFromPURL(ctx context.Context, p *purl.PURL) ([]Tag, error)

FetchTagsFromPURL fetches git tags using a PURL's repository_url qualifier.

func (*Client) ForgeFor added in v0.1.1 

func (c *Client) ForgeFor(domain string) (Forge, error)

ForgeFor returns the Forge implementation registered for the given domain.

func (*Client) ListRepositories added in v0.1.1 

func (c *Client) ListRepositories(ctx context.Context, domain, owner string, opts ListOptions) ([]Repository, error)

ListRepositories lists all repositories for an owner on the given domain.

func (*Client) RegisterDomain 

func (c *Client) RegisterDomain(ctx context.Context, domain, token string) error

RegisterDomain detects the forge type for a domain and registers it.

type Forge 

type Forge interface {
	FetchRepository(ctx context.Context, owner, repo string) (*Repository, error)
	FetchTags(ctx context.Context, owner, repo string) ([]Tag, error)
	ListRepositories(ctx context.Context, owner string, opts ListOptions) ([]Repository, error)
}

Forge is the interface each forge backend implements.

type ForgeType 

type ForgeType string

ForgeType identifies which forge software a domain runs. 

const (
	GitHub    ForgeType = "github"
	GitLab    ForgeType = "gitlab"
	Gitea     ForgeType = "gitea"
	Forgejo   ForgeType = "forgejo"
	Bitbucket ForgeType = "bitbucket"
	Unknown   ForgeType = "unknown"
)

func DetectForgeType 

func DetectForgeType(ctx context.Context, domain string) (ForgeType, error)

DetectForgeType probes a domain to identify which forge software it runs. It checks HTTP response headers first, then falls back to API endpoints.

type ForkFilter added in v0.1.1 

type ForkFilter int

ForkFilter controls how forked repositories are handled in list operations. 

const (
	ForkInclude ForkFilter = iota
	ForkExclude
	ForkOnly
)

type HTTPError 

type HTTPError struct {
	StatusCode int
	URL        string
	Body       string
}

HTTPError represents a non-OK HTTP response from a forge API.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type ListOptions added in v0.1.1 

type ListOptions struct {
	Archived ArchivedFilter
	Forks    ForkFilter
	PerPage  int
}

ListOptions configures a ListRepositories call.

type Option 

type Option func(*Client)

Option configures a Client.

func WithGitLab 

func WithGitLab(domain, token string) Option

WithGitLab registers a self-hosted GitLab instance.

func WithGitea 

func WithGitea(domain, token string) Option

WithGitea registers a self-hosted Gitea or Forgejo instance.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient overrides the default HTTP client used by forge backends.

func WithToken 

func WithToken(domain, token string) Option

WithToken sets the API token for the given domain.

type Repository 

type Repository struct {
	FullName            string    `json:"full_name"`
	Owner               string    `json:"owner"`
	Name                string    `json:"name"`
	Description         string    `json:"description,omitempty"`
	Homepage            string    `json:"homepage,omitempty"`
	HTMLURL             string    `json:"html_url"`
	Language            string    `json:"language,omitempty"`
	License             string    `json:"license,omitempty"` // SPDX identifier
	DefaultBranch       string    `json:"default_branch,omitempty"`
	Fork                bool      `json:"fork"`
	Archived            bool      `json:"archived"`
	Private             bool      `json:"private"`
	MirrorURL           string    `json:"mirror_url,omitempty"`
	SourceName          string    `json:"source_name,omitempty"` // fork parent full name
	Size                int       `json:"size"`
	StargazersCount     int       `json:"stargazers_count"`
	ForksCount          int       `json:"forks_count"`
	OpenIssuesCount     int       `json:"open_issues_count"`
	SubscribersCount    int       `json:"subscribers_count"`
	HasIssues           bool      `json:"has_issues"`
	PullRequestsEnabled bool      `json:"pull_requests_enabled"`
	Topics              []string  `json:"topics,omitempty"`
	LogoURL             string    `json:"logo_url,omitempty"`
	CreatedAt           time.Time `json:"created_at"`
	UpdatedAt           time.Time `json:"updated_at"`
	PushedAt            time.Time `json:"pushed_at,omitzero"`
}

Repository holds normalized metadata about a source code repository, independent of which forge hosts it.

func FilterRepos added in v0.1.1 

func FilterRepos(repos []Repository, opts ListOptions) []Repository

FilterRepos applies archived and fork filters to a slice of repositories.

type Tag 

type Tag struct {
	Name   string `json:"name"`
	Commit string `json:"commit"` // SHA
}

Tag represents a git tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.