github

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Jan 7, 2026 License: GPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package github provides a wrapper around GitHub's APIs in a manner compliant with the forge.Forge interface.

Index

Constants

View Source 
const (
	DefaultURL    = "https://github.com"
	DefaultAPIURL = "https://api.github.com"
)

Default URLs for GitHub and its API.

Variables

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

ErrLabelNotFound indicates that a label that we were expecting was not found in the repository.

Functions

This section is empty.

Types

type AuthenticationToken 

type AuthenticationToken struct {
	forge.AuthenticationToken

	// GitHubCLI is true if we should use GitHub CLI for API requests.
	//
	// If true, AccessToken is not used.
	GitHubCLI bool `json:"github_cli,omitempty"`

	// AccessToken is the GitHub access token.
	AccessToken string `json:"access_token,omitempty"`
}

AuthenticationToken defines the token returned by the GitHub forge.

type CLIAuthenticator 

type CLIAuthenticator struct {
	GH string // required
	// contains filtered or unexported fields
}

CLIAuthenticator implements GitHub CLI authentication flow. This doesn't do anything special besides checking if the user is logged in.

func (*CLIAuthenticator) Authenticate 

func (a *CLIAuthenticator) Authenticate(context.Context, ui.View) (*AuthenticationToken, error)

Authenticate checks if the user is authenticated with GitHub CLI.

type CLITokenSource 

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

CLITokenSource is an oauth2 token source that uses the GitHub CLI to get a token.

This is not super safe and we should probably nuke it.

func (*CLITokenSource) Token 

func (ts *CLITokenSource) Token() (*oauth2.Token, error)

Token returns an oauth2 token using the GitHub CLI.

type DeviceFlowAuthenticator 

type DeviceFlowAuthenticator struct {
	// Endpoint is the OAuth endpoint to use.
	Endpoint oauth2.Endpoint

	// ClientID for the OAuth or GitHub App.
	ClientID string

	// Scopes specifies the OAuth scopes to request.
	Scopes []string
}

DeviceFlowAuthenticator implements the OAuth device flow for GitHub. This is used for OAuth and GitHub App authentication.

func (*DeviceFlowAuthenticator) Authenticate 

func (a *DeviceFlowAuthenticator) Authenticate(ctx context.Context, view ui.View) (*AuthenticationToken, error)

Authenticate executes the OAuth authentication flow.

type Forge 

type Forge struct {
	Options Options

	// Log specifies the logger to use.
	Log *silog.Logger
}

Forge builds a GitHub Forge.

func (*Forge) APIURL 

func (f *Forge) APIURL() string

APIURL returns the base API URL configured for the GitHub Forge or the default URL if none is set.

func (*Forge) AuthenticationFlow 

func (f *Forge) AuthenticationFlow(ctx context.Context, view ui.View) (forge.AuthenticationToken, error)

AuthenticationFlow prompts the user to authenticate with GitHub. This rejects the request if the user is already authenticated with a GITHUB_TOKEN environment variable.

func (*Forge) CLIPlugin 

func (f *Forge) CLIPlugin() any

CLIPlugin returns the CLI plugin for the GitHub Forge.

func (*Forge) ChangeTemplatePaths 

func (f *Forge) ChangeTemplatePaths() []string

ChangeTemplatePaths reports the allowed paths for possible PR templates.

Ref https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository.

func (*Forge) ClearAuthenticationToken 

func (f *Forge) ClearAuthenticationToken(stash secret.Stash) error

ClearAuthenticationToken removes the authentication token from the stash.

func (*Forge) ID 

func (*Forge) ID() string

ID reports a unique key for this forge.

func (*Forge) LoadAuthenticationToken 

func (f *Forge) LoadAuthenticationToken(stash secret.Stash) (forge.AuthenticationToken, error)

LoadAuthenticationToken loads the authentication token from the stash. If the user has set GITHUB_TOKEN, it will be used instead.

func (*Forge) MarshalChangeID added in v0.10.0 

func (*Forge) MarshalChangeID(cid forge.ChangeID) (json.RawMessage, error)

MarshalChangeID serializes a PR into JSON.

func (*Forge) MarshalChangeMetadata 

func (*Forge) MarshalChangeMetadata(md forge.ChangeMetadata) (json.RawMessage, error)

MarshalChangeMetadata serializes a PRMetadata into JSON.

func (*Forge) OpenRepository added in v0.13.0 

func (f *Forge) OpenRepository(ctx context.Context, tok forge.AuthenticationToken, id forge.RepositoryID) (forge.Repository, error)

OpenRepository opens the GitHub repository that the given ID points to.

func (*Forge) ParseRemoteURL added in v0.13.0 

func (f *Forge) ParseRemoteURL(remoteURL string) (forge.RepositoryID, error)

ParseRemoteURL parses a GitHub remote URL and returns a RepositoryID if the URL matches.

func (*Forge) SaveAuthenticationToken 

func (f *Forge) SaveAuthenticationToken(stash secret.Stash, t forge.AuthenticationToken) error

SaveAuthenticationToken saves the given authentication token to the stash.

func (*Forge) URL 

func (f *Forge) URL() string

URL returns the base URL configured for the GitHub Forge or the default URL if none is set.

func (*Forge) UnmarshalChangeID added in v0.10.0 

func (*Forge) UnmarshalChangeID(data json.RawMessage) (forge.ChangeID, error)

UnmarshalChangeID deserializes a PR from JSON.

func (*Forge) UnmarshalChangeMetadata 

func (*Forge) UnmarshalChangeMetadata(data json.RawMessage) (forge.ChangeMetadata, error)

UnmarshalChangeMetadata deserializes a PRMetadata from JSON.

type Options 

type Options struct {
	// URL is the URL for GitHub.
	// Override this for testing or GitHub Enterprise.
	URL string `name:"github-url" hidden:"" config:"forge.github.url" env:"GITHUB_URL" help:"Base URL for GitHub web requests"`

	// APIURL is the URL for the GitHub API.
	// Override this for testing or GitHub Enterprise.
	APIURL string `name:"github-api-url" hidden:"" config:"forge.github.apiUrl" env:"GITHUB_API_URL" help:"Base URL for GitHub API requests"`

	// Token is a fixed token used to authenticate with GitHub.
	// This may be used to skip the login flow.
	Token string `name:"github-token" hidden:"" env:"GITHUB_TOKEN" help:"GitHub API token"`
}

Options defines command line options for the GitHub Forge. These are all hidden in the CLI, and are expected to be set only via environment variables.

type PATAuthenticator 

type PATAuthenticator struct{}

PATAuthenticator implements PAT authentication for GitHub.

func (*PATAuthenticator) Authenticate 

func (a *PATAuthenticator) Authenticate(_ context.Context, view ui.View) (*AuthenticationToken, error)

Authenticate prompts the user for a Personal Access Token, validates it, and returns the token if successful.

type PR 

type PR struct {
	// Number is the pull request number.
	// This will always be set.
	Number int `json:"number"`

	// GQLID is the GraphQL ID of the change.
	// This may be nil or empty.
	GQLID githubv4.ID `json:"gqlID,omitempty"`
}

PR uniquely identifies a PR in a GitHub repository. It's a valid forge.ChangeID.

func (*PR) String 

func (id *PR) String() string

func (*PR) UnmarshalJSON 

func (id *PR) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a GitHub change ID. It accepts the following formats: 

{"number": 123, "gqlID": "..."}
123

The second format is for backwards compatibility.

type PRComment 

type PRComment struct {
	GQLID githubv4.ID `json:"gqlID,omitempty"`
	URL   string      `json:"url,omitempty"`
}

PRComment is a ChangeCommentID for a GitHub PR comment.

func (*PRComment) String 

func (c *PRComment) String() string

type PRMetadata 

type PRMetadata struct {
	PR *PR `json:"pr,omitempty"`

	NavigationComment *PRComment `json:"comment,omitempty"`
}

PRMetadata is the metadata for a pull request.

func (*PRMetadata) ChangeID 

func (m *PRMetadata) ChangeID() forge.ChangeID

ChangeID reports the change ID of the pull request.

func (*PRMetadata) ForgeID 

func (*PRMetadata) ForgeID() string

ForgeID reports the forge ID that owns this metadata.

func (*PRMetadata) NavigationCommentID added in v0.5.0 

func (m *PRMetadata) NavigationCommentID() forge.ChangeCommentID

NavigationCommentID reports the comment ID of the navigation comment left on the pull request.

func (*PRMetadata) SetNavigationCommentID added in v0.5.0 

func (m *PRMetadata) SetNavigationCommentID(id forge.ChangeCommentID)

SetNavigationCommentID sets the comment ID of the navigation comment left on the pull request.

id may be nil.

type Repository 

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

Repository is a GitHub repository.

func (*Repository) ChangesStates added in v0.15.0 

func (r *Repository) ChangesStates(ctx context.Context, ids []forge.ChangeID) ([]forge.ChangeState, error)

ChangesStates retrieves the states of the given changes in bulk.

func (*Repository) CreateLabel added in v0.16.0 

func (r *Repository) CreateLabel(ctx context.Context, name string) (githubv4.ID, error)

CreateLabel creates a label in the repository with the given name and returns its GraphQL ID.

func (*Repository) DeleteChangeComment 

func (r *Repository) DeleteChangeComment(
	ctx context.Context,
	id forge.ChangeCommentID,
) error

DeleteChangeComment deletes an existing comment on a PR.

func (*Repository) DeleteLabel added in v0.16.0 

func (r *Repository) DeleteLabel(ctx context.Context, labelID githubv4.ID) error

DeleteLabel deletes a label from the repository by its ID. Use CreateLabel or LabelID to get the ID of a label. If the label does not exist, it returns nil error.

func (*Repository) EditChange 

func (r *Repository) EditChange(ctx context.Context, fid forge.ChangeID, opts forge.EditChangeOptions) error

EditChange edits an existing change in a repository.

func (*Repository) FindChangeByID 

func (r *Repository) FindChangeByID(ctx context.Context, id forge.ChangeID) (*forge.FindChangeItem, error)

FindChangeByID searches for a change with the given ID.

func (*Repository) FindChangesByBranch 

func (r *Repository) FindChangesByBranch(ctx context.Context, branch string, opts forge.FindChangesOptions) ([]*forge.FindChangeItem, error)

FindChangesByBranch searches for changes with the given branch name. It returns both, open and closed changes. Only recent changes are returned, limited by the given limit.

func (*Repository) Forge 

func (r *Repository) Forge() forge.Forge

Forge returns the forge this repository belongs to.

func (*Repository) LabelID added in v0.16.0 

func (r *Repository) LabelID(ctx context.Context, name string) (githubv4.ID, error)

LabelID returns the ID of a label by its name. It returns ErrLabelNotFound if the label does not exist.

func (*Repository) ListChangeComments added in v0.5.0 

func (r *Repository) ListChangeComments(
	ctx context.Context,
	id forge.ChangeID,
	options *forge.ListChangeCommentsOptions,
) iter.Seq2[*forge.ListChangeCommentItem, error]

ListChangeComments lists comments on a PR, optionally applying the given filtering options.

func (*Repository) ListChangeTemplates 

func (r *Repository) ListChangeTemplates(ctx context.Context) ([]*forge.ChangeTemplate, error)

ListChangeTemplates returns PR templates defined in the repository.

func (*Repository) NewChangeMetadata 

func (r *Repository) NewChangeMetadata(
	ctx context.Context,
	id forge.ChangeID,
) (forge.ChangeMetadata, error)

NewChangeMetadata returns the metadata for a pull request.

func (*Repository) PostChangeComment 

func (r *Repository) PostChangeComment(
	ctx context.Context,
	id forge.ChangeID,
	markdown string,
) (forge.ChangeCommentID, error)

PostChangeComment posts a new comment on a PR.

func (*Repository) RefExists added in v0.15.0 

func (r *Repository) RefExists(ctx context.Context, ref string) (bool, error)

RefExists checks if a reference exists in the repository. ref must be a fully qualified reference name,

func (*Repository) SubmitChange 

func (r *Repository) SubmitChange(ctx context.Context, req forge.SubmitChangeRequest) (forge.SubmitChangeResult, error)

SubmitChange creates a new change in a repository.

func (*Repository) UpdateChangeComment 

func (r *Repository) UpdateChangeComment(
	ctx context.Context,
	id forge.ChangeCommentID,
	markdown string,
) error

UpdateChangeComment updates the contents of an existing comment on a PR.

type RepositoryID added in v0.13.0 

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

RepositoryID is a unique identifier for a GitHub repository.

func (*RepositoryID) ChangeURL added in v0.13.0 

func (rid *RepositoryID) ChangeURL(id forge.ChangeID) string

ChangeURL returns a URL to view a change on GitHub.

func (*RepositoryID) String added in v0.13.0 

func (rid *RepositoryID) String() string

String returns a human-readable name for the repository ID.

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.