githubutil

package
v0.0.8 Latest Latest
Warning

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

 Go to latest Published: Nov 19, 2025 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TreeModeFile       = "100644"
	TreeModeExecutable = "100755"
	TreeModeDir        = "040000"
	TreeModeSubmodule  = "160000"
	TreeModeGitlink    = "120000"
)

Git tree entry mode constants defined by https://docs.github.com/en/rest/git/trees?apiVersion=2022-11-28#create-a-tree--parameters

Variables

View Source 
var (
	// ErrFileNotExists indicates that the requested file does not exist in the specified GitHub repository and branch.
	ErrFileNotExists = errors.New("file does not exist in the given repository and branch")
	// ErrRepositoryNotExists indicates that the requested repository does not exist.
	ErrRepositoryNotExists = errors.New("repository does not exist")
	// ErrNoAuthProvided indicates that no GitHubAuthFlags fields are filled in. It can be used to
	// skip actions that require auth when no auth is provided.
	//
	// This error is not used if any of the flags are set, e.g. if app auth is partially
	// configured. This indicates an issue with the command call and needs to be fixed.
	ErrNoAuthProvided = errors.New("no GitHub authentication provided")
)

Types of error that may be returned from the GitHub API that the caller may want to handle.

View Source 
var NewJWTTokenDebugLogger *log.Logger = log.New(io.Discard, "", 0)

NewJWTTokenDebugLogger is printed to when generating a JWT token. Assign this to a logger if debug output is desired. Defaults to discarding output.

Functions

func BindPATFlag 

func BindPATFlag() *string

BindPATFlag returns a flag to specify the personal access token. If possible, a command should instead use BindGitHubAuthFlags to support both PAT and app auth.

func BindRepoFlag 

func BindRepoFlag() *string

BindRepoFlag returns a flag to specify a GitHub repo to target. Parse it with ParseRepoFlag.

func CreateBranch added in v0.0.7 

func CreateBranch(ctx context.Context, client *github.Client, owner, repo, branchName, baseBranch string) error

func DownloadFile added in v0.0.3 

func DownloadFile(ctx context.Context, client *github.Client, owner, repo, ref, path string) ([]byte, error)

DownloadFile downloads a file from a given repository.

func FetchEachPage 

func FetchEachPage(f func(options github.ListOptions) (*github.Response, error)) error

FetchEachPage helps fetch all data from a GitHub API call that may or may not span multiple pages. FetchEachPage initially calls f with no paging parameters, then inspects the GitHub response to see if there are more pages to fetch. If so, it constructs paging parameters that will fetch the next page and calls f again. This repeats until there aren't any more pages.

Note that FetchEachPage doesn't process any of the result data, and doesn't actually call the GitHub API. f must do this itself. This allows FetchEachPage to work with any GitHub API.

func FetchRepository added in v0.0.6 

func FetchRepository(ctx context.Context, client *github.Client, owner, repo string) (*github.Repository, error)

FetchRepository fetches a repository from GitHub or returns an error. If the GitHub API error matches one of the errors defined in this package, it is wrapped. Retries if necessary.

func FullyCreateFork added in v0.0.6 

func FullyCreateFork(ctx context.Context, client *github.Client, upstreamOwner, repo string) (*github.Repository, error)

FullyCreateFork creates a fork of the given repository under the PAT owner's account, waits for the fork to be fully created, and returns its full information.

func ListDirFiles added in v0.0.7 

func ListDirFiles(ctx context.Context, client *github.Client, owner, repo, ref, dir string) ([]*github.RepositoryContent, error)

func NewClient 

func NewClient(ctx context.Context, pat string) (*github.Client, error)

NewClient creates a GitHub client using the given personal access token.

func PATScopes added in v0.0.6 

func PATScopes(ctx context.Context, client *github.Client) ([]string, error)

PATScopes gets the scopes of the client's PAT by reading a simple API call's response headers.

func ParseRepoFlag 

func ParseRepoFlag(repo *string) (owner, name string, err error)

ParseRepoFlag splits a given repo (owner/name) into owner and name, or returns an error.

func Retry 

func Retry(f func() error) error

Retry runs f up to 'retryAttempts' times, printing the error if one is encountered. Handles GitHub rate limit exceeded errors by waiting, if the reset will happen reasonably soon.

func UploadFile added in v0.0.2 

func UploadFile(ctx context.Context, client *github.Client, owner, repo, branch, path, message string, content []byte) error

UploadFile is a function that will upload a file to a given repository.

Types

type FS added in v0.0.7 

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

func NewRefFS added in v0.0.7 

func NewRefFS(ctx context.Context, client *github.Client, owner, repo, ref string) *FS

func (*FS) ReadDir added in v0.0.7 

func (r *FS) ReadDir(name string) ([]fs.DirEntry, error)

func (*FS) ReadFile added in v0.0.7 

func (r *FS) ReadFile(name string) ([]byte, error)

type FSDirEntry added in v0.0.7 

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

func (*FSDirEntry) Info added in v0.0.7 

func (r *FSDirEntry) Info() (fs.FileInfo, error)

func (*FSDirEntry) IsDir added in v0.0.7 

func (r *FSDirEntry) IsDir() bool

func (*FSDirEntry) ModTime added in v0.0.7 

func (r *FSDirEntry) ModTime() time.Time

func (*FSDirEntry) Mode added in v0.0.7 

func (r *FSDirEntry) Mode() fs.FileMode

func (*FSDirEntry) Name added in v0.0.7 

func (r *FSDirEntry) Name() string

func (*FSDirEntry) Size added in v0.0.7 

func (r *FSDirEntry) Size() int64

func (*FSDirEntry) Sys added in v0.0.7 

func (r *FSDirEntry) Sys() any

func (*FSDirEntry) Type added in v0.0.7 

func (r *FSDirEntry) Type() fs.FileMode

type GitHubAPIAuther added in v0.0.7 

type GitHubAPIAuther interface {
	// GetIdentity returns the identity (username or app name) that GitHub would refer to this
	// auther by.
	GetIdentity() (string, error)

	HTTPRequestAuther
	gitcmd.URLAuther
}

GitHubAPIAuther authenticates HTTP requests and GitHub URLs using the types of auth that are used to auth to the GitHub API.

type GitHubAppAuther added in v0.0.7 

type GitHubAppAuther struct {
	ClientID       string
	InstallationID int64
	PrivateKey     string // The GitHub App's private key (PEM format)
}

GitHubAppAuther authenticates using a GitHub App instead of a PAT.

func (GitHubAppAuther) GetIdentity added in v0.0.7 

func (a GitHubAppAuther) GetIdentity() (string, error)

func (GitHubAppAuther) InsertAuth added in v0.0.7 

func (a GitHubAppAuther) InsertAuth(url string) string

func (GitHubAppAuther) InsertHTTPAuth added in v0.0.7 

func (a GitHubAppAuther) InsertHTTPAuth(req *http.Request) error

type GitHubAuthFlags added in v0.0.7 

type GitHubAuthFlags struct {
	GitHubPat             *string
	GitHubAppClientID     *string
	GitHubAppInstallation *int64
	GitHubAppPrivateKey   *string
}

func BindGitHubAuthFlags added in v0.0.7 

func BindGitHubAuthFlags(user string) *GitHubAuthFlags

BindGitHubAuthFlags creates gitHubAuthFlags with the 'flag' package, globally registering them in the flag package so ParseBoundFlags will find them.

If user is specified, it is inserted into the middle of the flag name. This lets the func be called multiple times to set up multiple users/apps. It's inserted into the middle so the sorted "-h" output shows all the user/app's auth flags adjacent to each other, and so we can include a reminder about which values are associated with each other.

func (*GitHubAuthFlags) NewAppClient added in v0.0.7 

func (f *GitHubAuthFlags) NewAppClient(ctx context.Context) (*github.Client, error)

NewAppClient returns a GitHub client for the GitHub App, not the installation of the app. This client can be used to get information about the app itself, like its name.

If not enough information is present in f, returns ErrNoAuthProvided.

func (*GitHubAuthFlags) NewAuther added in v0.0.7 

func (f *GitHubAuthFlags) NewAuther() (GitHubAPIAuther, error)

NewAuther returns an auther based on the flags (e.g. PAT, GitHub App).

func (*GitHubAuthFlags) NewClient added in v0.0.7 

func (f *GitHubAuthFlags) NewClient(ctx context.Context) (*github.Client, error)

NewClient returns a GitHub client based on the flags (e.g. PAT, GitHub App).

If not enough information is present in f, returns ErrNoAuthProvided.

type GitHubPATAuther added in v0.0.7 

type GitHubPATAuther struct {
	// User to authenticate as. GitHub APIs don't care what this is, but this value is used if set.
	User string
	// PAT to authenticate with.
	PAT string
}

GitHubPATAuther adds a username and password into the https-style GitHub URL.

func (GitHubPATAuther) GetIdentity added in v0.0.7 

func (a GitHubPATAuther) GetIdentity() (string, error)

func (GitHubPATAuther) InsertAuth added in v0.0.7 

func (a GitHubPATAuther) InsertAuth(url string) string

func (GitHubPATAuther) InsertHTTPAuth added in v0.0.7 

func (a GitHubPATAuther) InsertHTTPAuth(req *http.Request) error

type GitHubSSHAuther added in v0.0.7 

type GitHubSSHAuther struct{}

GitHubSSHAuther turns an https-style GitHub URL into an SSH-style GitHub URL.

func (GitHubSSHAuther) InsertAuth added in v0.0.7 

func (GitHubSSHAuther) InsertAuth(url string) string

type HTTPRequestAuther added in v0.0.7 

type HTTPRequestAuther interface {
	// InsertHTTPAuth inserts authentication into the request, if applicable.
	InsertHTTPAuth(req *http.Request) error
}

HTTPRequestAuther adds some kind of HTTP authentication to a request.

type SimplifiedFS added in v0.0.7 

type SimplifiedFS interface {
	// ReadDir reads the named directory
	// and returns a list of directory entries sorted by filename.
	ReadDir(name string) ([]fs.DirEntry, error)

	// ReadFile reads the named file and returns its contents.
	// A successful call returns a nil error, not io.EOF.
	// (Because ReadFile reads the whole file, the expected EOF
	// from the final Read is not treated as an error to be reported.)
	//
	// The caller is permitted to modify the returned byte slice.
	// This method should return a copy of the underlying data.
	ReadFile(name string) ([]byte, error)
}

SimplifiedFS specifies the methods from fs.ReadDirFS and fs.ReadFileFS without the Open method from fs.FS. fs.FS is general purpose, and not needed for current use cases of NewRefFS.

Note that os.DirFS does implement SimplifiedFS, so SimplifiedFS can be used as a common way to read the local FS and also GitHub.

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.