github

Documentation

Overview

Package github reads the person's GitHub budget: the hourly REST core limit and the GraphQL limit every session, every gh call 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 REST request is conditional (the ETag of the last answer), so a 304 costs nothing; the GraphQL one is a rateLimit query, one point.

Index

• Constants
• Variables
• func PushesBranch(workflow []byte, branch string) (bool, error)
• func RefStates(ctx context.Context, run GH, refs []PR) (map[PR]RefState, error)
• func RunGH(ctx context.Context, args ...string) ([]byte, error)
• func Token(ctx context.Context) (string, error)
• type BaseRelease
  • func ReadBaseRelease(ctx context.Context, run GH, repo string, n int) (BaseRelease, 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 GraphQL
  • func ProbeGraphQL(ctx context.Context, client *http.Client, token string, now time.Time) GraphQL
  • func (g *GraphQL) Blocks(now time.Time) bool
• 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 RefState
• type Roster
  • func ReadRoster(ctx context.Context, client *http.Client, token, org string, now time.Time) (Roster, error)
  • func (r Roster) Answer(login string) string
• 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 (
	Member    = "member"
	NotMember = "not a member"
)

The answers of an org membership question.

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 AutoReleaseWorkflow = ".github/workflows/zz_generated.auto_release.yaml"

AutoReleaseWorkflow is the Auto-release workflow devctl generates: on a push to a branch its on.push filter names, it tags the merge commit.

const SquashRoute = "plain squash merge"

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

Variables

var ErrPermission = errors.New("permission missing")

ErrPermission is a token that may not read an org's whole membership: it sees the public members only, so its "not a member" would be a guess.

Functions

func PushesBranch

func PushesBranch(workflow []byte, branch string) (bool, error)

PushesBranch says whether a workflow runs on a push to branch, by its on: trigger and GitHub's branch filters (branches with ! negations, the last matching pattern deciding; branches-ignore; a tags filter alone leaves branch pushes out).

func RefStates

func RefStates(ctx context.Context, run GH, refs []PR) (map[PR]RefState, error)

RefStates reads in one GraphQL request the state of each issue or pull request of refs, and for a closed issue the pull request or commit whose closing keyword closed it. A reference GitHub does not answer is missing from the map.

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 BaseRelease

type BaseRelease struct {
	Base string
	Auto bool
}

BaseRelease is how a pull request's base branch releases: Auto when the Auto-release workflow on the branch runs on a push to it, so a merge into it is tagged; otherwise its tags are cut by hand (a maintenance branch, a fork line's backport branch).

func ReadBaseRelease

func ReadBaseRelease(ctx context.Context, run GH, repo string, n int) (BaseRelease, error)

ReadBaseRelease reads repo#n's base branch and the Auto-release workflow on it, two requests. A branch without the workflow has no auto-release; an error is GitHub not answering either.

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"`
	// GraphQL is the GraphQL limit; nil when it was not read.
	GraphQL *GraphQL `json:"graphql,omitempty"`
}

Budget is the core rate limit as GitHub reported it, and the GraphQL limit beside 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 GraphQL

type GraphQL struct {
	Limit     int `json:"limit"`
	Remaining int `json:"remaining"`
	Used      int `json:"used"`
	// Reset is when the refusal ends: the hourly reset of a spent limit,
	// Retry-After of a secondary one; zero when GitHub named no time.
	Reset time.Time `json:"reset,omitzero"`
	// Refused is GitHub's words while it refuses GraphQL calls, empty while
	// it answers them.
	Refused string `json:"refused,omitempty"`
	// Secondary says the refusal is a secondary limit (too many concurrent
	// or too fast calls), not the hourly limit spent.
	Secondary bool `json:"secondary,omitempty"`
	// Err is why the limit could not be read.
	Err string `json:"error,omitempty"`
}

GraphQL is the GraphQL limit as GitHub reported it for a real query.

func ProbeGraphQL

func ProbeGraphQL(ctx context.Context, client *http.Client, token string, now time.Time) GraphQL

ProbeGraphQL reads the GraphQL limit with a real query, so a refusal shows even while the counter looks healthy: a secondary limit refuses with headroom left.

func (*GraphQL) Blocks

func (g *GraphQL) Blocks(now time.Time) bool

Blocks says the refusal still holds at now: a refusal without a reset holds until a reading says otherwise.

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 RefState

type RefState struct {
	State  string
	Closer string
}

RefState is the state of an issue or pull request as GitHub answered: OPEN, CLOSED or MERGED, and for an issue a closing keyword closed, what closed it (Closer): the pull request whose merge did, as owner/repo#n, or a bare commit as "commit <sha>". Empty for a close by hand.

type Roster

type Roster struct {
	Org string `json:"org"`
	// Members are the logins, lower case and sorted.
	Members []string  `json:"members"`
	At      time.Time `json:"at"`
}

Roster is an org's members as a token that may read them all saw them.

func ReadRoster

func ReadRoster(ctx context.Context, client *http.Client, token, org string, now time.Time) (Roster, error)

ReadRoster reads org's members with token. The token's own membership comes first: only an active member's token, holding the read:org scope (or the App's members permission), lists the private members too; any other answer is ErrPermission, never an empty or public-only roster.

func (Roster) Answer

func (r Roster) Answer(login string) string

Answer is login's membership by the roster: Member or NotMember.

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.