rerun

package
v8.125.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source
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.

View Source
const (
	CommandPR      = "pr rerun"
	CommandRelease = "release rerun"
)

The commands, as their documents name them.

View Source
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.

View Source
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

func NoPipeline(what string) error

NoPipeline is exit 3 for a head or tag CircleCI has not built.

Types

type Document

type Document struct {
	agentcli.Envelope
	*Result
}

Document is the commands' JSON: the envelope and the result.

func NewDocument

func NewDocument(command, repository string) Document

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 Pipeline

type Pipeline struct {
	ID     string `json:"id"`
	Number int64  `json:"number"`
	URL    string `json:"url"`
}

Pipeline is the CircleCI pipeline whose workflows were considered.

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.

func NewResult

func NewResult(repository string) *Result

NewResult is an empty result for repository.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL