ghpr

Documentation

Index

• type Author
• type Change
  • func NewChange(repo Repo, branch string, creds Credentials, fn UpdateFunc) Change
  • func (c *Change) Push() error
• type Credentials
• type PR
  • func NewPR(ctx context.Context, change Change, creds Credentials) PR
  • func (p *PR) Create(ctx context.Context, targetBranch string, title string, body string) error
  • func (p *PR) GetGithubPR(ctx context.Context) (*github.PullRequest, error)
  • func (p *PR) Merge(ctx context.Context, mergeMethod string) error
  • func (p *PR) URL() (string, error)
  • func (p *PR) WaitForMergeStatus(ctx context.Context, strategy StatusWaitStrategy) error
  • func (p *PR) WaitForPRStatus(ctx context.Context, strategy StatusWaitStrategy) error
• type Repo
  • func NewRepo(owner string, name string) Repo
  • func (r *Repo) Clone(creds Credentials) error
  • func (r *Repo) Close() error
• type StatusWaitStrategy
• type UpdateFunc

Examples

• Change.Push
• NewPR
• PR.Create
• PR.Merge
• PR.WaitForMergeStatus
• PR.WaitForPRStatus
• Repo.Clone

Types

type Author

type Author struct {
	Name  string
	Email string
}

Author represents information about the creator of a commit

type Change

type Change struct {
	Branch string
	// contains filtered or unexported fields
}

func NewChange

func NewChange(repo Repo, branch string, creds Credentials, fn UpdateFunc) Change

NewChange creates a new Change object with the supplied parameters

func (*Change) Push

func (c *Change) Push() error

Push the change to the remote repository. First applies your update function to the supplied branch and pushes to a remote branch of the same name

Example

package main

import (
	"github.com/go-git/go-git/v5"
	"github.com/go-git/go-git/v5/plumbing/object"
	"github.com/shteou/go-ghpr/pkg/ghpr"
)

func updater(w *git.Worktree) (string, *object.Signature, error) {
	_, err := w.Remove("test-file")
	if err != nil {
		return "", nil, err
	}

	return "chore: remove obsolete test-file", &object.Signature{Name: "Stew", Email: "shteou@gmail.com"}, nil
}

func main() {
	creds := ghpr.Credentials{Username: "shteou", Token: "test"}

	repo := ghpr.NewRepo("shteou", "go-ghpr")
	defer repo.Close()

	err := repo.Clone(creds)
	if err != nil {
		return
	}

	change := ghpr.NewChange(repo, "test-branch", creds, updater)
	err = change.Push()
}

type Credentials

type Credentials struct {
	Username string
	Token    string
}

Credentials represents a GitHub username and PAT

type PR

type PR struct {
	Number int

	PRSha     string
	MergedSha string
	// contains filtered or unexported fields
}

func NewPR

func NewPR(ctx context.Context, change Change, creds Credentials) PR

NewPR creates a new PR object. The supplied context may be used over the course of the PR object's lifetime

Example

change, _ := basicChange()

_ = ghpr.NewPR(context.Background(), *change, creds())

func (*PR) Create

func (p *PR) Create(ctx context.Context, targetBranch string, title string, body string) error

Create a PR in Github from the Change's source branch to the supplied target branch

Example

basicChange, _ := basicChange()
pr := ghpr.NewPR(context.Background(), *basicChange, creds())
_ = pr.Create(context.Background(), "main", "chore: remove obsolete files", "")

url, _ := pr.URL()
fmt.Printf("New pull request raised at %s\n", url)

func (*PR) GetGithubPR

func (p *PR) GetGithubPR(ctx context.Context) (*github.PullRequest, error)

GetGithubPR feches the latest Github PR object directly

func (*PR) Merge

func (p *PR) Merge(ctx context.Context, mergeMethod string) error

Merge the PR using the supplied mergeMethod (one of merge, rebase or squash).

Example

pr, _ := basicPR()
_ = pr.Create(context.Background(), "main", "chore: remove obsolete files", "")

strategy := ghpr.StatusWaitStrategy{MinPollTime: 10 * time.Second, MaxPollTime: 60 * time.Second, PollBackoffFactor: 1.05, WaitStatusContext: "Semantic Pull Request"}
_ = pr.WaitForPRStatus(context.Background(), strategy)

_ = pr.Merge(context.Background(), "squash")

func (*PR) URL

func (p *PR) URL() (string, error)

URL fetches the URL for the GitHub PR without any additional calls to GitHub The function returns an error if the PR has not yet been created

func (*PR) WaitForMergeStatus

func (p *PR) WaitForMergeStatus(ctx context.Context, strategy StatusWaitStrategy) error

WaitForMergeStatus polls for a status on the merge commit (to your target branch).

Example

pr, _ := basicPR()
_ = pr.Create(context.Background(), "main", "chore: remove obsolete files", "")

strategy := ghpr.StatusWaitStrategy{MinPollTime: 10 * time.Second, MaxPollTime: 60 * time.Second, PollBackoffFactor: 1.05, WaitStatusContext: "Semantic Pull Request"}
_ = pr.WaitForPRStatus(context.Background(), strategy)
_ = pr.Merge(context.Background(), "squash")

_ = pr.WaitForMergeStatus(context.Background(), strategy)

func (*PR) WaitForPRStatus

func (p *PR) WaitForPRStatus(ctx context.Context, strategy StatusWaitStrategy) error

WaitForPRStatus polls for a status with exponential backoff, as defined by the StatusWaitStrategy parameter.

Example

pr, _ := basicPR()
_ = pr.Create(context.Background(), "main", "chore: remove obsolete files", "")

strategy := ghpr.StatusWaitStrategy{
	MinPollTime:       10 * time.Second,
	MaxPollTime:       60 * time.Second,
	PollBackoffFactor: 1.05,
	WaitStatusContext: "Semantic Pull Request",
}
_ = pr.WaitForPRStatus(context.Background(), strategy)

type Repo

type Repo struct {
	Name  string
	Owner string
	// contains filtered or unexported fields
}

func NewRepo

func NewRepo(owner string, name string) Repo

NewRepo creates a new Repo object with the supplied parameters

func (*Repo) Clone

func (r *Repo) Clone(creds Credentials) error

Clone the remote repository to a temporary directory

Example

package main

import (
	"github.com/shteou/go-ghpr/pkg/ghpr"
)

func main() {
	repo := ghpr.NewRepo("shteou", "go-ghpr")
	defer repo.Close()

	_ = repo.Clone(ghpr.Credentials{Username: "shteou", Token: "test"})
}

func (*Repo) Close

func (r *Repo) Close() error

Close removes the contents of the temporary directory

type StatusWaitStrategy

type StatusWaitStrategy struct {
	// The initial wait time
	MinPollTime time.Duration
	// The max wait time when polling for a status
	MaxPollTime time.Duration
	// The poll time will be multiplied by this (up to max)
	PollBackoffFactor float32
	// WaitStatusContext indicates the name of the status check to wait for
	WaitStatusContext string
}

StatusWaitStrategy describes how to wait for a GitHub status check

type UpdateFunc

type UpdateFunc func(w *git.Worktree) (string, *object.Signature, error)

UpdateFunc is a callback function which should create a series of changes to the git WorkTree. These changes will be automatically committed on successful return by the PushCommit function