Documentation
¶
Overview ¶
Package rerun is what `devctl pr rerun` and `devctl release rerun` share: given the CircleCI pipeline of a pull request's head or of a tag, every finished workflow of it that failed is rerun from failed -- its failed jobs and the jobs that depend on them, the passed ones kept -- with the CircleCI login of `devctl auth login`. A pipeline that never got a workflow (its setup workflow done and the continuation never created, or pending without a workflow) is sent its push webhook delivery again through GitHub (Redelivery), once per head. The rerun is started, not waited for: `devctl pr wait` and `devctl release wait` wait for it.
Index ¶
- Constants
- func FromFailed(ctx context.Context, client *circleciclient.Client, org, repo string, ...) error
- func NewCircleCI(ctx context.Context, require func(context.Context) (authstore.Token, error), ...) (*circleciclient.Client, error)
- func NewGitHub(ctx context.Context, owner string, ...) (*githubclient.Client, authstore.Token, error)
- func NoPipeline(what string) error
- type Document
- type Hooks
- type Pipeline
- type Redelivery
- type RedeliveryResult
- type Result
- type Workflow
Constants ¶
const ( // OutcomeRedelivered: the push delivery was sent again; CircleCI creates a // new pipeline for it. OutcomeRedelivered = "redelivered" // OutcomeAlreadyRedelivered: the push delivery was sent again before and // the pipeline it created has no workflow either; a second redelivery is // not sent. OutcomeAlreadyRedelivered = "already_redelivered" )
The outcomes of a redelivery.
const ( CommandPR = "pr rerun" CommandRelease = "release rerun" )
The commands, as their documents name them.
const ( // OutcomeRerun: the workflow failed and its rerun from failed started. OutcomeRerun = "rerun" // OutcomeRunning: the workflow has not finished; CircleCI reruns a // finished workflow only. OutcomeRunning = "running" // OutcomeNoFailedJob: the workflow was canceled (or unauthorized) // without a failed job to rerun. OutcomeNoFailedJob = "no_failed_job" // OutcomeNothing: the workflow did not fail. OutcomeNothing = "nothing_to_rerun" // OutcomeRefused: CircleCI refused the rerun; the reason says why. OutcomeRefused = "refused" )
The outcomes of one workflow.
const StalledAfter = 5 * time.Minute
StalledAfter is how long a pipeline may go without a workflow before its push webhook is redelivered: a setup workflow continues within a minute or two, and a continuation CircleCI accepted is created within seconds.
Variables ¶
This section is empty.
Functions ¶
func FromFailed ¶
func FromFailed(ctx context.Context, client *circleciclient.Client, org, repo string, pipeline *circleciclient.Pipeline, result *Result, warn func(string), redelivery Redelivery) error
FromFailed reruns the failed workflows of pipeline of org/repo from failed, recording each workflow in result as it goes. It returns nil when at least one rerun started (a warning names a workflow that is still running), exit 5 refused when nothing failed yet but a workflow is still running, and exit 3 not applicable when no workflow failed. A rerun CircleCI refuses with 403 is exit 8, naming the login that grants write access. A pipeline that never got a workflow is handed to redelivery, which sends its push webhook delivery again once it is StalledAfter old.
func NewCircleCI ¶
func NewCircleCI(ctx context.Context, require func(context.Context) (authstore.Token, error), endpoints agentcli.Endpoints, transport http.RoundTripper, warn func(string)) (*circleciclient.Client, error)
NewCircleCI is the CircleCI client on the keychain login require returns, its expiry warning passed to warn. Reads go through transport, which retries them; the rerun itself, a POST, is sent once.
func NewGitHub ¶ added in v8.125.0
func NewGitHub(ctx context.Context, owner string, app, person func(context.Context) (authstore.Token, error), endpoints agentcli.Endpoints, transport http.RoundTripper) (*githubclient.Client, authstore.Token, error)
NewGitHub is the GitHub client of owner's repositories on the identity authexec.RepositoryToken picks (the App login for an owner the App is installed on, the person's gh login elsewhere) and that token, built the way devctl pr wait builds its own; reads go through transport.
func NoPipeline ¶
NoPipeline is exit 3 for a head or tag CircleCI has not built.
Types ¶
type Document ¶
Document is the commands' JSON: the envelope and the result.
func NewDocument ¶
NewDocument starts the document of command for repository.
type Hooks ¶ added in v8.125.0
type Hooks interface {
ListHooks(ctx context.Context, owner, repo string) ([]*github.Hook, error)
ListHookDeliveries(ctx context.Context, owner, repo string, hookID int64) ([]*github.HookDelivery, error)
HookDelivery(ctx context.Context, owner, repo string, hookID, deliveryID int64) (*github.HookDelivery, error)
RedeliverHookDelivery(ctx context.Context, owner, repo string, hookID, deliveryID int64) error
}
Hooks is the GitHub webhook API of a repository: the part of githubclient.Client a redelivery uses.
type Redelivery ¶ added in v8.125.0
type Redelivery struct {
// Hooks is asked for the webhook API and the identity it acts as
// ([authexec.Identity]) only when the pipeline has no workflow; nil
// reports such a pipeline without a redelivery (exit 5).
Hooks func(ctx context.Context) (Hooks, string, error)
// Ref is the git ref the push carried, refs/tags/<tag> for a tag, which
// identifies the delivery; empty for a branch head, whose delivery is the
// push of the pipeline's revision.
Ref string
// Now is the clock; nil reads time.Now.
Now func() time.Time
}
Redelivery is the way out of a pipeline that never got a workflow (its setup workflow finished and the continuation was never created, or the pipeline stays pending without a workflow): the push webhook delivery that created it is sent again, so CircleCI creates a new pipeline for the head. Once per head: a delivery sent again before is not sent a second time.
type RedeliveryResult ¶ added in v8.125.0
type RedeliveryResult struct {
HookID int64 `json:"hookId"`
HookURL string `json:"hookUrl"`
DeliveryID int64 `json:"deliveryId"`
GUID string `json:"guid"`
DeliveredAt time.Time `json:"deliveredAt"`
// Ref and After are the push as the delivery carried it.
Ref string `json:"ref"`
After string `json:"after"`
// Outcome is one of redelivered, already_redelivered, refused.
Outcome string `json:"outcome"`
// RedeliveredAt is when the delivery was sent again before
// (already_redelivered).
RedeliveredAt *time.Time `json:"redeliveredAt,omitempty"`
}
RedeliveryResult is the redelivery in the command's document: the hook, the delivery sent again and what came of it.
type Result ¶
type Result struct {
Repository string `json:"repository"`
// Number is the pull request of `pr rerun`.
Number int `json:"number,omitempty"`
// Tag is the tag of `release rerun`, as CircleCI built it.
Tag string `json:"tag,omitempty"`
// HeadSHA is the revision the pipeline built.
HeadSHA string `json:"headSha,omitempty"`
// Pipeline is absent when CircleCI has no pipeline for the head or tag.
Pipeline *Pipeline `json:"pipeline,omitempty"`
Workflows []Workflow `json:"workflows"`
// Redelivery is the push webhook delivery sent again for a pipeline
// without a workflow; absent when the pipeline has workflows to judge.
Redelivery *RedeliveryResult `json:"redelivery,omitempty"`
}
Result is the commands' part of the document.
type Workflow ¶
type Workflow struct {
Name string `json:"name"`
ID string `json:"id"`
Status string `json:"status"`
URL string `json:"url"`
// FailedJobs are the failed jobs as CircleCI lists them, by name; the
// listing can lag behind the workflow's status.
FailedJobs []string `json:"failedJobs"`
// Outcome is one of rerun, running, no_failed_job, nothing_to_rerun,
// refused.
Outcome string `json:"outcome"`
// RerunID and RerunURL are the new workflow of a rerun.
RerunID string `json:"rerunId,omitempty"`
RerunURL string `json:"rerunUrl,omitempty"`
}
Workflow is the newest run of one workflow name of the pipeline and what the command did with it.