forges

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: MIT Imports: 11 Imported by: 1

README

forges

Go library and CLI for working with git forges. Supports GitHub, GitLab, Gitea/Forgejo, and Bitbucket Cloud through a single interface.

CLI

go install github.com/git-pkgs/forge/cmd/forge@latest

The CLI detects which forge to use from your git remote, or you can set it with --forge-type.

forge repo view
forge issue list --state open
forge pr create --title "Fix bug" --head fix-branch
forge release list
forge ci list
forge branch list
forge label list
forge api repos/{owner}/{repo}

Run forge --help for the full command list.

Authentication

Store tokens with forge auth login:

forge auth login                          # interactive: asks domain + token
forge auth login --domain github.com --token ghp_abc123
forge auth login --domain gitea.example.com --token abc123 --type gitea

Check what's configured with forge auth status.

Tokens are resolved in this order: CLI flags, environment variables (FORGE_TOKEN, GITHUB_TOKEN/GH_TOKEN, GITLAB_TOKEN, GITEA_TOKEN, BITBUCKET_TOKEN), then the config file at ~/.config/forge/config.

Configuration

Two config files, both INI-style:

~/.config/forge/config stores tokens and user preferences (respects XDG_CONFIG_HOME):

[default]
output = json

[github.com]
token = ghp_abc123

[gitea.example.com]
type = gitea
token = abc123

.forge in the repo root is for per-project settings, committed to the repo, no tokens:

[default]
forge-type = gitlab

[gitlab.internal.dev]
type = gitlab

This tells forge that the project uses GitLab and that gitlab.internal.dev is a GitLab instance, so contributors don't each need --forge-type or FORGE_HOST.

Precedence from highest to lowest: CLI flags, environment variables, .forge, ~/.config/forge/config, built-in defaults.

Library

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

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")

The Forge interface exposes services for repos, issues, pull requests, releases, CI, branches, labels, milestones, deploy keys, and secrets. Each backend implements these using its native SDK.

f, _ := client.ForgeFor("github.com")
issues, _ := f.Issues().List(ctx, "octocat", "hello-world", forges.ListIssueOpts{State: "open"})
pr, _ := f.PullRequests().Get(ctx, "octocat", "hello-world", 42)

Self-hosted instances can be registered explicitly or detected automatically:

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

// or auto-detect
err := client.RegisterDomain(ctx, "git.example.com", token)

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

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

Documentation

Index

Constants

This section is empty.

Variables

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

ErrNotFound is returned when the requested resource does not exist.

View Source 
var ErrNotSupported = errors.New("not supported by this forge")

ErrNotSupported is returned when a forge does not support an operation.

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 

type ArchivedFilter int

ArchivedFilter controls how archived repositories are handled in list operations. 

const (
	ArchivedInclude ArchivedFilter = iota
	ArchivedExclude
	ArchivedOnly
)

type Branch 

type Branch struct {
	Name      string `json:"name"`
	SHA       string `json:"sha"`
	Protected bool   `json:"protected"`
	Default   bool   `json:"default"`
}

Branch holds normalized metadata about a git branch.

type BranchService 

type BranchService interface {
	List(ctx context.Context, owner, repo string, opts ListBranchOpts) ([]Branch, error)
	Create(ctx context.Context, owner, repo, name, from string) (*Branch, error)
	Delete(ctx context.Context, owner, repo, name string) error
}

BranchService provides operations on repository branches.

type CIJob 

type CIJob struct {
	ID         int64      `json:"id"`
	Name       string     `json:"name"`
	Status     string     `json:"status"`
	Conclusion string     `json:"conclusion,omitempty"`
	HTMLURL    string     `json:"html_url,omitempty"`
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

CIJob holds normalized metadata about a CI job.

type CIRun 

type CIRun struct {
	ID         int64      `json:"id"`
	Title      string     `json:"title"`
	Status     string     `json:"status"`     // queued, running, completed, failed, success, cancelled
	Conclusion string     `json:"conclusion"` // success, failure, cancelled, skipped (GitHub-specific)
	Branch     string     `json:"branch"`
	SHA        string     `json:"sha"`
	Event      string     `json:"event,omitempty"` // push, pull_request, etc.
	Author     User       `json:"author"`
	HTMLURL    string     `json:"html_url"`
	Jobs       []CIJob    `json:"jobs,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

CIRun holds normalized metadata about a CI pipeline or workflow run.

type CIService 

type CIService interface {
	ListRuns(ctx context.Context, owner, repo string, opts ListCIRunOpts) ([]CIRun, error)
	GetRun(ctx context.Context, owner, repo string, runID int64) (*CIRun, error)
	TriggerRun(ctx context.Context, owner, repo string, opts TriggerCIRunOpts) error
	CancelRun(ctx context.Context, owner, repo string, runID int64) error
	RetryRun(ctx context.Context, owner, repo string, runID int64) error
	GetJobLog(ctx context.Context, owner, repo string, jobID int64) (io.ReadCloser, error)
}

CIService provides operations on CI/CD pipelines and workflow runs.

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 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 

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

ForgeFor returns the Forge implementation registered for the given domain.

func (*Client) HTTPClient 

func (c *Client) HTTPClient() *http.Client

HTTPClient returns the HTTP client configured on this Client, or nil.

func (*Client) ListRepositories 

func (c *Client) ListRepositories(ctx context.Context, domain, owner string, opts ListRepoOpts) ([]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, builders ForgeBuilders) error

RegisterDomain detects the forge type for a domain and registers the appropriate Forge using the provided builder functions.

func (*Client) Tokens 

func (c *Client) Tokens() map[string]string

Tokens returns the token map so callers can read tokens set via WithToken.

type Comment 

type Comment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	Author    User      `json:"author"`
	HTMLURL   string    `json:"html_url"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Comment holds normalized metadata about an issue or PR comment.

type CreateDeployKeyOpts 

type CreateDeployKeyOpts struct {
	Title    string
	Key      string
	ReadOnly bool
}

CreateDeployKeyOpts holds options for adding a deploy key.

type CreateIssueOpts 

type CreateIssueOpts struct {
	Title     string
	Body      string
	Assignees []string
	Labels    []string
	Milestone string
}

CreateIssueOpts holds options for creating an issue.

type CreateLabelOpts 

type CreateLabelOpts struct {
	Name        string
	Color       string
	Description string
}

CreateLabelOpts holds options for creating a label.

type CreateMilestoneOpts 

type CreateMilestoneOpts struct {
	Title       string
	Description string
	DueDate     *time.Time
}

CreateMilestoneOpts holds options for creating a milestone.

type CreatePROpts 

type CreatePROpts struct {
	Title     string
	Body      string
	Head      string // source branch
	Base      string // target branch
	Draft     bool
	Assignees []string
	Labels    []string
	Milestone string
	Reviewers []string
}

CreatePROpts holds options for creating a pull request.

type CreateReleaseOpts 

type CreateReleaseOpts struct {
	TagName       string
	Target        string
	Title         string
	Body          string
	Draft         bool
	Prerelease    bool
	GenerateNotes bool
}

CreateReleaseOpts holds options for creating a release.

type CreateRepoOpts 

type CreateRepoOpts struct {
	Name          string
	Description   string
	Visibility    Visibility
	Init          bool
	DefaultBranch string
	Readme        bool
	Gitignore     string
	License       string
	Owner         string // org or group; empty = authenticated user
}

CreateRepoOpts holds options for creating a repository.

type DeployKey 

type DeployKey struct {
	ID        int64     `json:"id"`
	Title     string    `json:"title"`
	Key       string    `json:"key"`
	ReadOnly  bool      `json:"read_only"`
	CreatedAt time.Time `json:"created_at"`
}

DeployKey holds normalized metadata about a deploy key.

type DeployKeyService 

type DeployKeyService interface {
	List(ctx context.Context, owner, repo string, opts ListDeployKeyOpts) ([]DeployKey, error)
	Get(ctx context.Context, owner, repo string, id int64) (*DeployKey, error)
	Create(ctx context.Context, owner, repo string, opts CreateDeployKeyOpts) (*DeployKey, error)
	Delete(ctx context.Context, owner, repo string, id int64) error
}

DeployKeyService provides operations on repository deploy keys.

type EditRepoOpts 

type EditRepoOpts struct {
	Description   *string
	Homepage      *string
	Visibility    Visibility
	DefaultBranch *string
	HasIssues     *bool
	HasPRs        *bool
}

EditRepoOpts holds options for editing a repository.

type Forge 

type Forge interface {
	Repos() RepoService
	Issues() IssueService
	PullRequests() PullRequestService
	Labels() LabelService
	Milestones() MilestoneService
	Releases() ReleaseService
	CI() CIService
	Branches() BranchService
	DeployKeys() DeployKeyService
	Secrets() SecretService
}

Forge is the interface each forge backend implements.

type ForgeBuilders 

type ForgeBuilders struct {
	GitHub func(baseURL, token string, hc *http.Client) Forge
	GitLab func(baseURL, token string, hc *http.Client) Forge
	Gitea  func(baseURL, token string, hc *http.Client) Forge
}

ForgeBuilders holds constructor functions for each forge type. Used by RegisterDomain to create the right forge after detection.

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, hc ...*http.Client) (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. If hc is nil, http.DefaultClient is used.

type ForkFilter 

type ForkFilter int

ForkFilter controls how forked repositories are handled in list operations. 

const (
	ForkInclude ForkFilter = iota
	ForkExclude
	ForkOnly
)

type ForkRepoOpts 

type ForkRepoOpts struct {
	Owner string // target owner/org; empty = authenticated user
	Name  string // new name; empty = keep original
}

ForkRepoOpts holds options for forking a repository.

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 Issue 

type Issue struct {
	Number    int        `json:"number"`
	Title     string     `json:"title"`
	Body      string     `json:"body"`
	State     string     `json:"state"` // "open" or "closed"
	Author    User       `json:"author"`
	Assignees []User     `json:"assignees,omitempty"`
	Labels    []Label    `json:"labels,omitempty"`
	Milestone *Milestone `json:"milestone,omitempty"`
	Comments  int        `json:"comments"`
	Locked    bool       `json:"locked"`
	HTMLURL   string     `json:"html_url"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	ClosedAt  *time.Time `json:"closed_at,omitempty"`
}

Issue holds normalized metadata about an issue.

type IssueService 

type IssueService interface {
	Get(ctx context.Context, owner, repo string, number int) (*Issue, error)
	List(ctx context.Context, owner, repo string, opts ListIssueOpts) ([]Issue, error)
	Create(ctx context.Context, owner, repo string, opts CreateIssueOpts) (*Issue, error)
	Update(ctx context.Context, owner, repo string, number int, opts UpdateIssueOpts) (*Issue, error)
	Close(ctx context.Context, owner, repo string, number int) error
	Reopen(ctx context.Context, owner, repo string, number int) error
	Delete(ctx context.Context, owner, repo string, number int) error
	CreateComment(ctx context.Context, owner, repo string, number int, body string) (*Comment, error)
	ListComments(ctx context.Context, owner, repo string, number int) ([]Comment, error)
}

IssueService provides operations on issues.

type Label 

type Label struct {
	Name        string `json:"name"`
	Color       string `json:"color,omitempty"`
	Description string `json:"description,omitempty"`
}

Label represents an issue or pull request label.

type LabelService 

type LabelService interface {
	List(ctx context.Context, owner, repo string, opts ListLabelOpts) ([]Label, error)
	Get(ctx context.Context, owner, repo, name string) (*Label, error)
	Create(ctx context.Context, owner, repo string, opts CreateLabelOpts) (*Label, error)
	Update(ctx context.Context, owner, repo, name string, opts UpdateLabelOpts) (*Label, error)
	Delete(ctx context.Context, owner, repo, name string) error
}

LabelService provides operations on repository labels.

type ListBranchOpts 

type ListBranchOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

ListBranchOpts holds options for listing branches.

type ListCIRunOpts 

type ListCIRunOpts struct {
	Branch   string
	Status   string
	User     string
	Workflow string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

ListCIRunOpts holds options for listing CI runs.

type ListDeployKeyOpts 

type ListDeployKeyOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

ListDeployKeyOpts holds options for listing deploy keys.

type ListIssueOpts 

type ListIssueOpts struct {
	State    string // open, closed, all
	Labels   []string
	Assignee string
	Author   string
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

ListIssueOpts holds options for listing issues.

type ListLabelOpts 

type ListLabelOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

ListLabelOpts holds options for listing labels.

type ListMilestoneOpts 

type ListMilestoneOpts struct {
	State   string // open, closed, all
	Limit   int    // max total results; 0 = unlimited
	Page    int    // starting page; 0 or 1 = first page
	PerPage int    // results per API request; 0 = default
}

ListMilestoneOpts holds options for listing milestones.

type ListPROpts 

type ListPROpts struct {
	State    string // open, closed, merged, all
	Labels   []string
	Assignee string
	Author   string
	Base     string
	Head     string
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

ListPROpts holds options for listing pull requests.

type ListReleaseOpts 

type ListReleaseOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

ListReleaseOpts holds options for listing releases.

type ListRepoOpts 

type ListRepoOpts struct {
	Archived ArchivedFilter
	Forks    ForkFilter
	Sort     string
	Order    string
	Limit    int // max total results; 0 = unlimited
	Page     int // starting page; 0 or 1 = first page
	PerPage  int // results per API request; 0 = default
}

ListRepoOpts configures a repo list call.

Pagination: Page and PerPage control the API page size and starting page. Limit caps the total number of results returned across all pages. When Limit is 0 all results are returned. PerPage defaults to a backend-specific value (typically 30-50) when 0.

type ListSecretOpts 

type ListSecretOpts struct {
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

ListSecretOpts holds options for listing secrets.

type MergePROpts 

type MergePROpts struct {
	Method  string // merge, squash, rebase
	Title   string // commit title
	Message string // commit message
	Delete  bool   // delete branch after merge
}

MergePROpts holds options for merging a pull request.

type Milestone 

type Milestone struct {
	Title       string     `json:"title"`
	Number      int        `json:"number"`
	Description string     `json:"description,omitempty"`
	State       string     `json:"state"`
	DueDate     *time.Time `json:"due_date,omitempty"`
}

Milestone represents a project milestone.

type MilestoneService 

type MilestoneService interface {
	List(ctx context.Context, owner, repo string, opts ListMilestoneOpts) ([]Milestone, error)
	Get(ctx context.Context, owner, repo string, id int) (*Milestone, error)
	Create(ctx context.Context, owner, repo string, opts CreateMilestoneOpts) (*Milestone, error)
	Update(ctx context.Context, owner, repo string, id int, opts UpdateMilestoneOpts) (*Milestone, error)
	Close(ctx context.Context, owner, repo string, id int) error
	Reopen(ctx context.Context, owner, repo string, id int) error
	Delete(ctx context.Context, owner, repo string, id int) error
}

MilestoneService provides operations on repository milestones.

type Option 

type Option func(*Client)

Option configures a Client.

func WithForge 

func WithForge(domain string, f Forge) Option

WithForge registers a Forge implementation for the given domain.

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 PullRequest 

type PullRequest struct {
	Number       int        `json:"number"`
	Title        string     `json:"title"`
	Body         string     `json:"body"`
	State        string     `json:"state"` // "open", "closed", or "merged"
	Draft        bool       `json:"draft"`
	Author       User       `json:"author"`
	Assignees    []User     `json:"assignees,omitempty"`
	Reviewers    []User     `json:"reviewers,omitempty"`
	Labels       []Label    `json:"labels,omitempty"`
	Milestone    *Milestone `json:"milestone,omitempty"`
	Head         string     `json:"head"` // head branch
	Base         string     `json:"base"` // base branch
	Mergeable    bool       `json:"mergeable"`
	Merged       bool       `json:"merged"`
	MergedBy     *User      `json:"merged_by,omitempty"`
	Comments     int        `json:"comments"`
	Additions    int        `json:"additions"`
	Deletions    int        `json:"deletions"`
	ChangedFiles int        `json:"changed_files"`
	HTMLURL      string     `json:"html_url"`
	DiffURL      string     `json:"diff_url,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	UpdatedAt    time.Time  `json:"updated_at"`
	MergedAt     *time.Time `json:"merged_at,omitempty"`
	ClosedAt     *time.Time `json:"closed_at,omitempty"`
}

PullRequest holds normalized metadata about a pull request (or merge request).

type PullRequestService 

type PullRequestService interface {
	Get(ctx context.Context, owner, repo string, number int) (*PullRequest, error)
	List(ctx context.Context, owner, repo string, opts ListPROpts) ([]PullRequest, error)
	Create(ctx context.Context, owner, repo string, opts CreatePROpts) (*PullRequest, error)
	Update(ctx context.Context, owner, repo string, number int, opts UpdatePROpts) (*PullRequest, error)
	Close(ctx context.Context, owner, repo string, number int) error
	Reopen(ctx context.Context, owner, repo string, number int) error
	Merge(ctx context.Context, owner, repo string, number int, opts MergePROpts) error
	Diff(ctx context.Context, owner, repo string, number int) (string, error)
	CreateComment(ctx context.Context, owner, repo string, number int, body string) (*Comment, error)
	ListComments(ctx context.Context, owner, repo string, number int) ([]Comment, error)
}

PullRequestService provides operations on pull requests (merge requests on GitLab).

type Release 

type Release struct {
	TagName     string         `json:"tag_name"`
	Title       string         `json:"title"`
	Body        string         `json:"body,omitempty"`
	Draft       bool           `json:"draft"`
	Prerelease  bool           `json:"prerelease"`
	Target      string         `json:"target,omitempty"`
	Author      User           `json:"author"`
	Assets      []ReleaseAsset `json:"assets,omitempty"`
	TarballURL  string         `json:"tarball_url,omitempty"`
	ZipballURL  string         `json:"zipball_url,omitempty"`
	HTMLURL     string         `json:"html_url"`
	CreatedAt   time.Time      `json:"created_at"`
	PublishedAt time.Time      `json:"published_at,omitzero"`
}

Release holds normalized metadata about a release.

type ReleaseAsset 

type ReleaseAsset struct {
	ID            int64     `json:"id"`
	Name          string    `json:"name"`
	Size          int       `json:"size"`
	DownloadCount int       `json:"download_count"`
	DownloadURL   string    `json:"download_url"`
	CreatedAt     time.Time `json:"created_at"`
}

ReleaseAsset holds metadata about a file attached to a release.

type ReleaseService 

type ReleaseService interface {
	List(ctx context.Context, owner, repo string, opts ListReleaseOpts) ([]Release, error)
	Get(ctx context.Context, owner, repo, tag string) (*Release, error)
	GetLatest(ctx context.Context, owner, repo string) (*Release, error)
	Create(ctx context.Context, owner, repo string, opts CreateReleaseOpts) (*Release, error)
	Update(ctx context.Context, owner, repo, tag string, opts UpdateReleaseOpts) (*Release, error)
	Delete(ctx context.Context, owner, repo, tag string) error
	UploadAsset(ctx context.Context, owner, repo, tag string, file *os.File) (*ReleaseAsset, error)
	DownloadAsset(ctx context.Context, owner, repo string, assetID int64) (io.ReadCloser, error)
}

ReleaseService provides operations on releases.

type RepoService 

type RepoService interface {
	Get(ctx context.Context, owner, repo string) (*Repository, error)
	List(ctx context.Context, owner string, opts ListRepoOpts) ([]Repository, error)
	Create(ctx context.Context, opts CreateRepoOpts) (*Repository, error)
	Edit(ctx context.Context, owner, repo string, opts EditRepoOpts) (*Repository, error)
	Delete(ctx context.Context, owner, repo string) error
	Fork(ctx context.Context, owner, repo string, opts ForkRepoOpts) (*Repository, error)
	ListTags(ctx context.Context, owner, repo string) ([]Tag, error)
	Search(ctx context.Context, opts SearchRepoOpts) ([]Repository, error)
}

RepoService provides operations on repositories.

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"`
	CloneURL            string    `json:"clone_url,omitempty"`
	SSHURL              string    `json:"ssh_url,omitempty"`
	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 

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

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

type SearchRepoOpts 

type SearchRepoOpts struct {
	Query   string
	Sort    string
	Order   string
	Limit   int // max total results; 0 = unlimited
	Page    int // starting page; 0 or 1 = first page
	PerPage int // results per API request; 0 = default
}

SearchRepoOpts holds options for searching repositories.

type Secret 

type Secret struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at,omitzero"`
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

Secret holds normalized metadata about a repository secret.

type SecretService 

type SecretService interface {
	List(ctx context.Context, owner, repo string, opts ListSecretOpts) ([]Secret, error)
	Set(ctx context.Context, owner, repo string, opts SetSecretOpts) error
	Delete(ctx context.Context, owner, repo, name string) error
}

SecretService provides operations on repository secrets.

type SetSecretOpts 

type SetSecretOpts struct {
	Name  string
	Value string
}

SetSecretOpts holds options for creating or updating a secret.

type Tag 

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

Tag represents a git tag.

type TriggerCIRunOpts 

type TriggerCIRunOpts struct {
	Workflow string
	Branch   string
	Inputs   map[string]string
}

TriggerCIRunOpts holds options for triggering a CI run.

type UpdateIssueOpts 

type UpdateIssueOpts struct {
	Title     *string
	Body      *string
	Assignees []string
	Labels    []string
	Milestone *string
}

UpdateIssueOpts holds options for updating an issue.

type UpdateLabelOpts 

type UpdateLabelOpts struct {
	Name        *string
	Color       *string
	Description *string
}

UpdateLabelOpts holds options for updating a label.

type UpdateMilestoneOpts 

type UpdateMilestoneOpts struct {
	Title       *string
	Description *string
	State       *string
	DueDate     *time.Time
}

UpdateMilestoneOpts holds options for updating a milestone.

type UpdatePROpts 

type UpdatePROpts struct {
	Title     *string
	Body      *string
	Base      *string
	Assignees []string
	Labels    []string
	Milestone *string
	Reviewers []string
}

UpdatePROpts holds options for updating a pull request.

type UpdateReleaseOpts 

type UpdateReleaseOpts struct {
	TagName    *string
	Target     *string
	Title      *string
	Body       *string
	Draft      *bool
	Prerelease *bool
}

UpdateReleaseOpts holds options for updating a release.

type User 

type User struct {
	Login     string `json:"login"`
	Name      string `json:"name,omitempty"`
	Email     string `json:"email,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	HTMLURL   string `json:"html_url,omitempty"`
	IsOrg     bool   `json:"is_org,omitempty"`
}

User holds normalized user/org metadata.

type Visibility 

type Visibility int

Visibility selects the visibility level for a new or edited repository. 

const (
	VisibilityDefault Visibility = iota
	VisibilityPublic
	VisibilityPrivate
	VisibilityInternal
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
forge command
internal
cli
config
output
resolve

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.