Documentation
¶
Overview ¶
Package ci is what `devctl ci jobs` and `devctl ci rerun` share: the job-level view of a CircleCI pipeline, which tells a slow job (its step still writing output) from a stuck one (no output for an hour), and the rerun of one workflow, once an hour, with the CircleCI login of `devctl auth login`. GitHub is not read: a pipeline or a workflow is named by what CircleCI calls it, the number or id the UI and `devctl pr wait` show.
Index ¶
- Constants
- func AwaitCanceled(ctx context.Context, client *circleciclient.Client, workflowID string, ...) (string, error)
- func Jobs(ctx context.Context, client *circleciclient.Client, org, repo, pipeline string, ...) error
- func Rerun(ctx context.Context, client *circleciclient.Client, ...) error
- type Job
- type JobsResult
- type Pipeline
- type RerunOptions
- type RerunResult
- type Run
- type Step
- type Workflow
Constants ¶
const ( CommandJobs = "ci jobs" CommandRerun = "ci rerun" )
The commands, as their documents name them.
const ( // OutcomeRerun: the rerun started. OutcomeRerun = "rerun" // OutcomeRefused: the rerun was not made; the reason says why. OutcomeRefused = "refused" )
The outcomes of `ci rerun`.
const (
CancelTimeout = 2 * time.Minute
)
CancelTimeout bounds the wait for a canceled workflow to read canceled, which CircleCI does on its own a little after the cancel; cancelPoll is how often it is read meanwhile.
const RerunWindow = time.Hour
RerunWindow is how long after a rerun of a workflow name in a pipeline the next rerun of that name is refused: one rerun per hour, so an agent that reruns on every poll cannot loop. The rule reads CircleCI, not a file: a rerun is a second run of the name in the pipeline, whoever started it.
Variables ¶
This section is empty.
Functions ¶
func AwaitCanceled ¶ added in v8.146.0
func AwaitCanceled(ctx context.Context, client *circleciclient.Client, workflowID string, clock agentcli.Clock) (string, error)
AwaitCanceled reads the workflow until it no longer runs and returns its status; exit 2 when it still runs after CancelTimeout.
func Jobs ¶
func Jobs(ctx context.Context, client *circleciclient.Client, org, repo, pipeline string, now time.Time, result *JobsResult, warn func(string)) error
Jobs reads pipeline, a number or an id, of org/repo at the job level into result as of now: every workflow run with its jobs, and for a running job the step it is in and when that step last wrote output. Exit 3 when CircleCI has no such pipeline of the repository. Jobs or steps CircleCI does not answer are a warning, not an outcome: the rest of the view still tells where the pipeline stands.
func Rerun ¶
func Rerun(ctx context.Context, client *circleciclient.Client, org, repo, workflowID string, opts RerunOptions, clock agentcli.Clock, result *RerunResult, warn func(string)) error
Rerun reruns workflowID of org/repo, recording what it did in result. The workflow has to belong to the repository (exit 3 otherwise, as for one CircleCI does not know). A rerun of the workflow's name made within RerunWindow is exit 5 naming it and when the hour ends. A workflow still running is exit 5 unless opts.Cancel cancels it first; a cancel that does not settle within CancelTimeout is exit 2. A rerun CircleCI refuses is exit 5 with its message, one it refuses with 403 exit 8 naming the login that grants Write access. The rerun is started, not waited for.
Types ¶
type Job ¶
type Job struct {
Name string `json:"name"`
// Number is the job's number in the project; absent for an approval and
// for a job that has not started.
Number int64 `json:"number,omitempty"`
Type string `json:"type"`
Status string `json:"status"`
StartedAt *time.Time `json:"startedAt,omitempty"`
StoppedAt *time.Time `json:"stoppedAt,omitempty"`
// DurationSeconds is how long the job ran, or has been running.
DurationSeconds int64 `json:"durationSeconds,omitempty"`
// Step is where a running job stands; absent for every other job, and
// for a running job whose steps CircleCI did not answer (a warning says
// so).
Step *Step `json:"step,omitempty"`
}
Job is one job of a workflow.
type JobsResult ¶
type JobsResult struct {
Repository string `json:"repository"`
// Pipeline is absent when CircleCI has no such pipeline.
Pipeline *Pipeline `json:"pipeline,omitempty"`
Workflows []Workflow `json:"workflows"`
}
JobsResult is the document part of `ci jobs`.
func NewJobsResult ¶
func NewJobsResult(repository string) *JobsResult
NewJobsResult is an empty result for repository.
type Pipeline ¶
type Pipeline struct {
ID string `json:"id"`
Number int64 `json:"number"`
State string `json:"state,omitempty"`
URL string `json:"url"`
CreatedAt *time.Time `json:"createdAt,omitempty"`
Branch string `json:"branch,omitempty"`
Tag string `json:"tag,omitempty"`
Revision string `json:"revision,omitempty"`
}
Pipeline is the CircleCI pipeline of a document.
type RerunOptions ¶
type RerunOptions struct {
// FromFailed reruns the failed jobs and the jobs that depend on them,
// the passed ones kept; off, every job runs again.
FromFailed bool
// Cancel cancels a workflow still running before the rerun, the
// recovery of a stuck one; off, a running workflow is refused.
Cancel bool
}
RerunOptions are the flags of `ci rerun`.
type RerunResult ¶
type RerunResult struct {
Repository string `json:"repository"`
// Pipeline and Workflow are absent when CircleCI has no such workflow.
Pipeline *Pipeline `json:"pipeline,omitempty"`
Workflow *Run `json:"workflow,omitempty"`
FromFailed bool `json:"fromFailed"`
// Canceled says whether the workflow was canceled before the rerun.
Canceled bool `json:"canceled"`
// Outcome is rerun or refused; empty when the run ended before deciding.
Outcome string `json:"outcome,omitempty"`
// RerunID and RerunURL are the new workflow of a rerun.
RerunID string `json:"rerunId,omitempty"`
RerunURL string `json:"rerunUrl,omitempty"`
// LastRerun is the rerun of the workflow's name made within RerunWindow,
// the one that refuses this call; absent otherwise.
LastRerun *Run `json:"lastRerun,omitempty"`
}
RerunResult is the document part of `ci rerun`.
func NewRerunResult ¶
func NewRerunResult(repository string) *RerunResult
NewRerunResult is an empty result for repository.
type Run ¶
type Run struct {
Name string `json:"name"`
ID string `json:"id"`
Status string `json:"status"`
URL string `json:"url"`
CreatedAt time.Time `json:"createdAt"`
StoppedAt *time.Time `json:"stoppedAt,omitempty"`
}
Run is one workflow run. A rerun is a second run of the same name in the same pipeline; the newest run of a name says where the pipeline stands.
type Step ¶
type Step struct {
Name string `json:"name"`
StartedAt *time.Time `json:"startedAt,omitempty"`
// EndedAt is set when the step finished and the job is between steps.
EndedAt *time.Time `json:"endedAt,omitempty"`
// RunningSeconds is how long the step has been running.
RunningSeconds int64 `json:"runningSeconds"`
// LastOutputAt is when the step last wrote a line; absent when it has
// written nothing yet.
LastOutputAt *time.Time `json:"lastOutputAt,omitempty"`
// OutputAgeSeconds is how long ago that was: seconds for a job that is
// slow, an hour for one that is stuck. 0 without LastOutputAt.
OutputAgeSeconds int64 `json:"outputAgeSeconds"`
}
Step is the step a running job is in: the last one that started.
type Workflow ¶
type Workflow struct {
Run
// Latest says whether this is the newest run of its name in the
// pipeline, the one that says where the pipeline stands; an older run
// is a rerun's predecessor.
Latest bool `json:"latest"`
Jobs []Job `json:"jobs"`
}
Workflow is one workflow run of the pipeline with its jobs. Every run is listed, reruns included, so what was rerun and when is visible.
Source Files