github

Documentation

Overview

Package github reads the person's GitHub REST budget: the hourly core limit every session, every devctl wait and the person's own developer portal login draw from.

The budget is read from the X-RateLimit headers of a real request, never from /rate_limit: that endpoint is exempt and reported a full budget while real requests were already refused. The request is conditional (the ETag of the last answer), so a 304 costs nothing.

Index

• Constants
• func RunGH(ctx context.Context, args ...string) ([]byte, error)
• func Token(ctx context.Context) (string, error)
• type Budget
  • func Probe(ctx context.Context, client *http.Client, token, repo, etag string) (Budget, string, error)
• type Check
  • func PullCheck(ctx context.Context, run GH, repo string, n int, name string) (Check, error)
• type GH
• type PR
  • func Lookup(ctx context.Context, run GH, pulls []PR, drafts []string) (map[PR]string, []PR, error)
• type Pull
  • func PullState(ctx context.Context, repo string, n int) (Pull, error)
• type Squash
  • func (s Squash) Run(ctx context.Context) SquashDoc
• type SquashDoc

Constants

const (
	CheckMissing = "missing"
	CheckPending = "pending"
	CheckPass    = "pass"
	CheckFail    = "fail"
)

The outcomes of a pull request's check on its head.

const (
	Open   = "OPEN"
	Merged = "MERGED"
	Closed = "CLOSED"
)

The states of a pull request.

const (
	SquashMerged        = 0
	SquashRed           = 1
	SquashTimeout       = 2
	SquashNotApplicable = 3
	SquashRefused       = 5
	SquashTooling       = 7
)

The plain squash merge's exit codes and verdicts, devctl pr merge's own (docs/pr-merge.md in giantswarm/devctl), so the gate reads either the same.

const SquashRoute = "plain squash merge"

SquashRoute names the route in the document and the gate's lines.

Functions

func RunGH

func RunGH(ctx context.Context, args ...string) ([]byte, error)

RunGH is GH through the gh binary.

func Token

func Token(ctx context.Context) (string, error)

Token returns the token of the gh CLI's login.

Types

type Budget

type Budget struct {
	Resource  string    `json:"resource"`
	Limit     int       `json:"limit"`
	Remaining int       `json:"remaining"`
	Used      int       `json:"used"`
	Reset     time.Time `json:"reset"`
}

Budget is the core rate limit as GitHub reported it.

func Probe

func Probe(ctx context.Context, client *http.Client, token, repo, etag string) (Budget, string, error)

Probe reads the budget with a conditional GET of repo ("owner/name") and returns it with the ETag to send next time.

type Check

type Check struct {
	// State is the pull request's: Open, Merged or Closed.
	State string
	// Outcome is CheckMissing when the head has no check of that name.
	Outcome string
	// URL is the check run's page.
	URL string
	// Annotations are the messages a failed check run annotated with its
	// own name as the title: what it found.
	Annotations []string
}

Check is one named check of a pull request's head and the pull request's state.

func PullCheck

func PullCheck(ctx context.Context, run GH, repo string, n int, name string) (Check, error)

PullCheck reads repo#n's state and the newest check run named name on its head (one GraphQL request); a failed one's annotations titled name take a second, which leaves out the runner's own ("Process completed with exit code 1").

type GH

type GH func(ctx context.Context, args ...string) ([]byte, error)

GH runs the gh CLI and returns its stdout; err carries its stderr.

type PR

type PR struct {
	Repo string `json:"repo"`
	N    int    `json:"n"`
}

PR is a pull request: its owner/repo and number.

func Lookup

func Lookup(ctx context.Context, run GH, pulls []PR, drafts []string) (map[PR]string, []PR, error)

Lookup reads in one GraphQL request the titles of pulls and the open draft pull requests of the repositories drafts (owner/repo), oldest first.

type Pull

type Pull struct {
	State    string    `json:"state"`
	MergedAt time.Time `json:"mergedAt"`
}

Pull is a pull request's state as the gh CLI reports it.

func PullState

func PullState(ctx context.Context, repo string, n int) (Pull, error)

PullState reads repo#n's state with the gh CLI's login (one GraphQL request).

type Squash

type Squash struct {
	GH       GH
	Repo     string
	Number   int
	Timeout  time.Duration
	Poll     time.Duration
	Progress io.Writer
	Now      func() time.Time
	Sleep    func(time.Duration)
}

Squash is one plain squash merge: the route of a repository devctl does not serve (its GitHub App login reaches the giantswarm organisation and public repositories only), made with the gh CLI's login as the person.

func (Squash) Run

func (s Squash) Run(ctx context.Context) SquashDoc

Run waits until the head's checks finished, all green, and squash-merges it through the merge API with that head as the expected one, the subject "<title> (#<n>)", then deletes the head branch. It refuses what devctl refuses before its wait: a draft, a closed, merged or conflicting pull request (3) and another human's (5). Its document says what happened; nothing waits for a release.

type SquashDoc

type SquashDoc struct {
	Command        string  `json:"command"`
	Route          string  `json:"route"`
	SchemaVersion  int     `json:"schemaVersion"`
	ExitCode       int     `json:"exitCode"`
	Verdict        string  `json:"verdict"`
	Reason         string  `json:"reason"`
	Repo           string  `json:"repository"`
	Number         int     `json:"number"`
	HeadSha        string  `json:"headSha,omitempty"`
	MergeCommitSha string  `json:"mergeCommitSha,omitempty"`
	Release        *string `json:"release"`
}

SquashDoc is the plain squash merge's JSON document, shaped as devctl pr merge's: the gate parses mergeCommitSha and release alike.