github

package
v0.0.0-...-5f133c6 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2024 License: BSD-3-Clause, BSD-3-Clause Imports: 17 Imported by: 0

README

Go Reference

Overview

This library provides methods and objects to easily perform common operations on github.

Specifically, it provides a simplified github client that always enforces timeouts, implements retries, and handles the pagination.

It also provides a library to handle and create "stable comments": comments appended to PRs used as mini-dashboards that are updated as your CI/CD or automation progresses through its work.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultContextFactory = TimeoutContextFactory(context.Background(), DefaultTimeout)
View Source 
var DefaultMarker = "staco-unfortunate-id"
View Source 
var DefaultTimeout = time.Second * 30

Functions

func NewDiffFromFlags 

func NewDiffFromFlags(fl *StableCommentDiffFlags) (jd.Diff, error)

func NewGithubError 

func NewGithubError(resp *github.Response, err error) error

Types

type CommentPayload 

type CommentPayload struct {
	Template string
	Content  string
}

type ContextFactory 

type ContextFactory func() (context.Context, context.CancelFunc)

ContextFactory creates a context for use with the github operations.

func TimeoutContextFactory 

func TimeoutContextFactory(ctx context.Context, timeout time.Duration) ContextFactory

TimeoutContextFactory returns a ContextFactory that will timeout the operations if they don't complete within the specified duration.

type DiffTransformer 

type DiffTransformer jd.Diff

func (*DiffTransformer) Apply 

func (dt *DiffTransformer) Apply(ijson string) (string, error)

type GithubError 

type GithubError struct {
	Err      error
	Response *github.Response
}

func (*GithubError) Error 

func (e *GithubError) Error() string

func (*GithubError) Unwrap 

func (e *GithubError) Unwrap() error

type GithubRepo 

type GithubRepo struct {
	Owner string // For example: "enfabrica"
	Name  string // For example: "enkit"
}

GithubRepo uniquely identifies a git repository on github.

func (*GithubRepo) Register 

func (fl *GithubRepo) Register(set kflags.FlagSet, prefix string) *GithubRepo

type JqTransformer 

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

func NewJqFromFlags 

func NewJqFromFlags(jqf *StableCommentJqFlags) (*JqTransformer, error)

func (*JqTransformer) Apply 

func (jt *JqTransformer) Apply(ijson string) (string, error)

type RepoClient 

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

RepoClient binds a git repository to a github.Client.

It provides a simplified API around some common operations.

func NewRepoClient 

func NewRepoClient(mods ...RepoClientModifier) (*RepoClient, error)

NewRepoClient instantiates a new RepoClient with the specified options.

A RepoClient object wraps a github.Client and a GithubRepo under a single object, and provides some simplified APIs for github access.

NewRepoClient accepts functional options. As a bare minimum, you must use WithRepo() and WithClient() or WithToken(), to ensure that a repo has been defined, and a github client initialized.

Alternatively, you can use FromFlags() to initialize all parameters from command line flags.

func (*RepoClient) AddPRComment 

func (rc *RepoClient) AddPRComment(prnumber int, body string) (int64, error)

AddPRComment adds a comment to the PR.

In github, PRs can have two kind of comments: those tied to a (commit, file, line) tuple, typically added as part of a review process, and those posted in free form on the PR, normally added at the end of a conversation.

This method adds a free form comment to a PR. Returns the comment id, used in other APIs.

func (*RepoClient) EditPRComment 

func (rc *RepoClient) EditPRComment(commentid int64, body string) error

EditPRComment adds a comment to the PR.

In github, PRs can have two kind of comments: those tied to a (commit, file, line) tuple, typically added as part of a review process, and those posted in free form on the PR, normally added at the end of a conversation.

This method edits a free form comment already posted in a PR.

func (*RepoClient) GetPRComments 

func (rc *RepoClient) GetPRComments(pr int) ([]*github.IssueComment, error)

GetPRComments returns the comments associated with a PR.

In github, PRs can have two kind of comments: those tied to a (commit, file, line) tuple, typically added as part of a review process, and those posted in free form on the PR, normally added at the end of a conversation.

This method returns the list of free form comments in a PR.

func (*RepoClient) GetPRReviewComments 

func (rc *RepoClient) GetPRReviewComments(prnumber int) ([]*github.PullRequestComment, error)

GetPRReviewComments returns the review comments of a PR.

In github, PRs can have two kind of comments: those tied to a (commit, file, line) tuple, typically added as part of a review process, and those posted in free form on the PR, normally added at the end of a conversation.

This method returns the review comments, those tied to a (commit, file, line).

type RepoClientFlags 

type RepoClientFlags struct {
	Token   string
	Repo    GithubRepo
	Retry   *retry.Flags
	Timeout time.Duration
}

func DefaultRepoClientFlags 

func DefaultRepoClientFlags() *RepoClientFlags

func (*RepoClientFlags) Register 

func (fl *RepoClientFlags) Register(set kflags.FlagSet, prefix string) *RepoClientFlags

type RepoClientModifier 

type RepoClientModifier func(*RepoClient) error

func RepoClientFromFlags 

func RepoClientFromFlags(ctx context.Context, fl *RepoClientFlags, rmods ...retry.Modifier) RepoClientModifier

RepoClientFromFlags initializes a RepoClient from command line flags.

To use this function, create a RepoClientFlags object using DefaultRepoClientFlags() and register the corresponding flags with Register().

func WithClient 

func WithClient(client *github.Client) RepoClientModifier

func WithContextFactory 

func WithContextFactory(ctx ContextFactory) RepoClientModifier

func WithRepo 

func WithRepo(repo GithubRepo) RepoClientModifier

func WithRetry 

func WithRetry(retry *retry.Options) RepoClientModifier

WithRetry configures the library to use the specified retry policy.

func WithToken 

func WithToken(ctx context.Context, token string) RepoClientModifier

WithToken creates a github client using the supplied static token.

The created client is configured with WithClient, the last WithClient specified takes priority over the rest.

type RepoClientModifiers 

type RepoClientModifiers []RepoClientModifier

func (RepoClientModifiers) Apply 

func (rcm RepoClientModifiers) Apply(rc *RepoClient) error

type StableComment 

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

StableComment is an object to manipulate and process stable github comments.

A "stable" github comment is a comment attached to a PR that is periodically updated to show some important information about the PR.

For example, it can be used by a BOT to compute a list of reviewers, and as the PR is updated with other commits, the list of reviewers is updated.

Or, as a CI job progresses, it can be used to post links or information about the status of the BUILD (useful links, detected errors, etc).

A naive BOT would just add new comments to a github PR, creating a poor user experience.

StableComment will instead post one comment, and then keep updating it.

The update operations support rendering a template with json, and allow for the state of the previous comment to be maintained.

For example: let's say that a CI job is running. At the beginning of the run it creates a "StableComment", made by a template rendering a list of json operations.

As the CI job continues, the "StableComment" API is invoked through independent CLI invocations (a "stateless" job - not a daemon), specifying a PATCH adding an operation to the previously posted json, causing operations to be added. The PATCH could look something like: 

[{"op":"add","path":"/operations/-","value":"{ ... json ...}"}]

Appending an element to an existing list.

func NewStableComment 

func NewStableComment(mods ...StableCommentModifier) (*StableComment, error)

func (*StableComment) FetchPRState 

func (sc *StableComment) FetchPRState(rc *RepoClient, pr int) (int64, string, string, error)

func (*StableComment) ParseComment 

func (sc *StableComment) ParseComment(comment string) (string, string, error)

ParseComment parses a string comment.

The string comment is normally retrieved from github, but this function can be used for scripts or tests.

Returns the parsed and validated json content and template.

If the error returns nil on Unwrap() it means there was no parsing or validation error - the supplied string did not contain metadata.

func (*StableComment) PostAction 

func (sc *StableComment) PostAction() string

PostAction describes the action that needs to be performed for this comment.

func (*StableComment) PostPayload 

func (sc *StableComment) PostPayload(rc *RepoClient, comment string, prnumber int) error

PostPayload posts a pre-formatted comment to the specified PR.

func (*StableComment) PostToPR 

func (sc *StableComment) PostToPR(rc *RepoClient, tr Transformer, prnumber int) error

func (*StableComment) PreparePayload 

func (sc *StableComment) PreparePayload(jsonvars string) (string, error)

PreparePayload prepares a comment to post based on the specified jsonvars.

jsonvars is a json payload, as a string.

Returns the payload, ready to be posted with PostPayload(), or an error.

func (*StableComment) PreparePayloadFromDiff 

func (sc *StableComment) PreparePayloadFromDiff(tr Transformer) (string, error)

func (*StableComment) UpdateFromPR 

func (sc *StableComment) UpdateFromPR(rc *RepoClient, pr int) error

type StableCommentDiffFlags 

type StableCommentDiffFlags struct {
	// Native jd format patch - as per https://github.com/josephburnett/jd#diff-language
	Diff string
	// RFC 7386 format.
	Patch string
	// RFC 6902 format.
	Merge string
}

func DefaultStableCommentDiffFlags 

func DefaultStableCommentDiffFlags() *StableCommentDiffFlags

func (*StableCommentDiffFlags) Register 

func (fl *StableCommentDiffFlags) Register(set kflags.FlagSet, prefix string) *StableCommentDiffFlags

type StableCommentFlags 

type StableCommentFlags struct {
	Marker      string
	Template    string
	JsonContent string
	JsonReset   bool
}

func DefaultStableCommentFlags 

func DefaultStableCommentFlags() *StableCommentFlags

func (*StableCommentFlags) Register 

func (fl *StableCommentFlags) Register(set kflags.FlagSet, prefix string) *StableCommentFlags

type StableCommentJqFlags 

type StableCommentJqFlags struct {
	Timeout time.Duration
	Code    string
}

func DefaultStableCommentJqFlags 

func DefaultStableCommentJqFlags() *StableCommentJqFlags

func (*StableCommentJqFlags) Register 

func (fl *StableCommentJqFlags) Register(set kflags.FlagSet, prefix string) *StableCommentJqFlags

type StableCommentModifier 

type StableCommentModifier func(*StableComment) error

func StableCommentFromFlags 

func StableCommentFromFlags(fl *StableCommentFlags) StableCommentModifier

func WithID 

func WithID(id int64) StableCommentModifier

func WithJsonContent 

func WithJsonContent(content string) StableCommentModifier

func WithJsonReset 

func WithJsonReset(reset bool) StableCommentModifier

func WithLogger 

func WithLogger(logger logger.Logger) StableCommentModifier

func WithMarker 

func WithMarker(marker string) StableCommentModifier

func WithTemplate 

func WithTemplate(template string) StableCommentModifier

type StableCommentModifiers 

type StableCommentModifiers []StableCommentModifier

func (StableCommentModifiers) Apply 

func (ms StableCommentModifiers) Apply(sc *StableComment) error

type StableCommentTransformerFlags 

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

func DefaultStableCommentTransformerFlags 

func DefaultStableCommentTransformerFlags() *StableCommentTransformerFlags

func (*StableCommentTransformerFlags) Register 

func (fl *StableCommentTransformerFlags) Register(
	set kflags.FlagSet, prefix string) *StableCommentTransformerFlags

type Transformer 

type Transformer interface {
	Apply(inputjson string) (string, error)
}

func NewTransformerFromFlags 

func NewTransformerFromFlags(fl *StableCommentTransformerFlags) (Transformer, error)

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.