github

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2024 License: GPL-3.0 Imports: 21 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

This section is empty.

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(ctx context.Context) (*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

	Stderr io.Writer // required
}

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) (*AuthenticationToken, error)

Authenticate executes the OAuth authentication flow.

type Forge 

type Forge struct {
	Options Options

	// Log specifies the logger to use.
	Log *log.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) (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) MarshalChangeMetadata 

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

MarshalChangeMetadata serializes a PRMetadata into JSON.

func (*Forge) MatchURL 

func (f *Forge) MatchURL(remoteURL string) bool

MatchURL reports whether the given URL is a GitHub URL.

func (*Forge) OpenURL 

func (f *Forge) OpenURL(ctx context.Context, tok forge.AuthenticationToken, remoteURL string) (forge.Repository, error)

OpenURL opens a GitHub repository from a remote URL. Returns forge.ErrUnsupportedURL if the URL is not a valid GitHub URL.

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) 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 {
	Stdin  io.Reader // required
	Stderr io.Writer // required
}

PATAuthenticator implements PAT authentication for GitHub.

func (*PATAuthenticator) Authenticate 

func (a *PATAuthenticator) Authenticate(ctx context.Context) (*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) ChangeIsMerged 

func (r *Repository) ChangeIsMerged(ctx context.Context, id forge.ChangeID) (bool, error)

ChangeIsMerged reports whether a change has been merged.

func (*Repository) DeleteChangeComment 

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

DeleteChangeComment deletes an existing comment on a PR.

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) ListChangeComments added in v0.5.0 

func (f *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 (f *Repository) NewChangeMetadata(
	ctx context.Context,
	id forge.ChangeID,
) (forge.ChangeMetadata, error)

NewChangeMetadata returns the metadata for a pull request.

func (*Repository) PostChangeComment 

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

PostChangeComment posts a new comment on a PR.

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 (f *Repository) UpdateChangeComment(
	ctx context.Context,
	id forge.ChangeCommentID,
	markdown string,
) error

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

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.