Documentation
¶
Overview ¶
Package prwait is the wait engine behind `devctl pr wait` (and the merge that follows it): one bounded, blocking call that returns when a pull request's head is green, red, or cannot become green as it is.
Green is the merge box's view, not `gh pr checks`': every check run and commit status of the head (the latest per name), every CircleCI workflow of the head revision (the newest run per name, read from CircleCI because a job behind `requires:` has posted nothing yet), no GitHub Actions run of the head still queued, running or awaiting approval, and every required status context reported. Draft, closed, conflicting and behind-a-strict-base end the wait before it starts.
Index ¶
Constants ¶
const ( // MinInterval is the shortest a poll waits, however large the budget. MinInterval = 15 * time.Second // MaxInterval is the longest a poll waits, however small the budget. MaxInterval = 60 * time.Second )
The bounds of the poll interval at scale 1.
const ( SourceCheckRun = "check_run" SourceStatus = "status" )
The check sources of the document.
const CircleCIConfigPath = ".circleci/config.yml"
CircleCIConfigPath is the file whose presence at the head makes CircleCI part of the verdict.
const DefaultTimeout = 30 * time.Minute
DefaultTimeout bounds a wait whose caller names none.
Variables ¶
This section is empty.
Functions ¶
func IsFork ¶ added in v8.82.0
func IsFork(pr *github.PullRequest) bool
IsFork says whether the head lives in another repository than the base.
func NotApplicable ¶ added in v8.82.0
func NotApplicable(pr *github.PullRequest) error
NotApplicable is the rule Wait applies before its first poll, for a caller that reads the pull request itself first (pr merge, whose refusals come before the wait): exit 3 for a pull request no wait can turn green, nil otherwise. The verdict is the one Wait would give.
Types ¶
type ActionRun ¶
type ActionRun struct {
Name string `json:"name"`
RunID int64 `json:"runId"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
URL string `json:"url"`
}
ActionRun is the latest GitHub Actions run of one workflow for the head.
type Check ¶
type Check struct {
Name string `json:"name"`
Source string `json:"source"`
// Status is queued, in_progress or completed for a check run; pending or
// completed for a status.
Status string `json:"status"`
// Conclusion is the check run's conclusion or the status's state once it
// is not pending; empty while unfinished.
Conclusion string `json:"conclusion"`
URL string `json:"url"`
// Required: branch protection or a ruleset of the base names this context.
Required bool `json:"required"`
}
Check is one check of the head as the merge box lists it: a check run (the latest run of that name) or a commit status (the latest of that context).
type CircleCI ¶
type CircleCI struct {
PipelineID string `json:"pipelineId"`
PipelineNumber int64 `json:"pipelineNumber"`
Workflows []Workflow `json:"workflows"`
}
CircleCI is the newest pipeline of the head revision and its workflows, the newest run per workflow name.
type Config ¶
type Config struct {
// GitHub is required. From [githubclient.NewConditional] its polls are
// conditional requests and Rate is the [githubclient.Conditional].
GitHub *githubclient.Client
// Rate is where the poll interval comes from; nil polls at the floor.
Rate RateSource
// CircleCI returns the client once the head is known to carry a CircleCI
// configuration; it is the place the CircleCI token is required, so an
// [agentcli.ExitCoder] it returns ends the wait with that code. nil
// means CircleCI is never consulted.
CircleCI func(ctx context.Context) (*circleciclient.Client, error)
// Clock defaults to the wall clock at scale 1.
Clock agentcli.Clock
// Progress may be nil.
Progress *agentcli.Progress
// Timeout defaults to DefaultTimeout.
Timeout time.Duration
}
Config configures a Waiter.
type RateSource ¶
type RateSource interface {
Rate() githubclient.RateLimit
}
RateSource reports the GitHub rate limit the newest response carried.
type Result ¶
type Result struct {
Repository string `json:"repository"`
Number int `json:"number"`
HeadSHA string `json:"headSha"`
BaseRef string `json:"baseRef"`
// Checks are the head's check runs and statuses, the latest per name.
Checks []Check `json:"checks"`
// CircleCI is absent when the head carries no CircleCI configuration or
// the repository has no CircleCI project.
CircleCI *CircleCI `json:"circleci,omitempty"`
// Actions are the head's GitHub Actions runs, the latest per workflow.
Actions []ActionRun `json:"actions"`
// Unfinished names what the head was still waiting for when the wait
// ended without a verdict.
Unfinished []string `json:"unfinished,omitempty"`
// Warnings are for the envelope: a head that changed under the wait, a
// CircleCI project that does not exist.
Warnings []string `json:"-"`
}
Result is the command's part of the document.
type Waiter ¶
type Waiter struct {
// contains filtered or unexported fields
}
Waiter runs waits.
func (*Waiter) Wait ¶
Wait blocks until owner/repo#number is green (nil), red or otherwise decided (an *agentcli.ExitError with the code of the table), or the timeout passes (exit 2, or 4 when a required context never reported). The Result is always returned, as far as it was filled; a tooling failure is any other error.
Source Files