Documentation
¶
Overview ¶
Package ci is what `devctl ci jobs`, `devctl ci job` 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), one job's steps with the end of its failed steps' output, 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 ReadJob(ctx context.Context, client *circleciclient.Client, org, repo, ref string, ...) error
- func Rerun(ctx context.Context, client *circleciclient.Client, ...) error
- type Job
- type JobDetail
- type JobResult
- type JobStep
- type JobsResult
- type Pipeline
- type RerunOptions
- type RerunResult
- type Run
- type Step
- type Workflow
Constants ¶
const ( CommandJobs = "ci jobs" CommandJob = "ci job" 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 DefaultJobLogLines = 200
DefaultJobLogLines is how many lines of a job's failed steps' output `ci job` keeps.
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 ReadJob ¶ added in v8.157.0
func ReadJob(ctx context.Context, client *circleciclient.Client, org, repo, ref string, lines int, result *JobResult, warn func(string)) error
ReadJob reads job number ref of org/repo into result: its status, its steps and the tail of its failed steps' output, lines of it. Exit 3 when CircleCI has no such job of the repository. Steps CircleCI does not answer are a warning; output it does not answer is the job's LogError.
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 JobDetail ¶ added in v8.157.0
type JobDetail struct {
Number int64 `json:"number"`
Name string `json:"name"`
Status string `json:"status"`
URL string `json:"url,omitempty"`
PipelineID string `json:"pipelineId,omitempty"`
WorkflowID string `json:"workflowId,omitempty"`
StartedAt *time.Time `json:"startedAt,omitempty"`
StoppedAt *time.Time `json:"stoppedAt,omitempty"`
Steps []JobStep `json:"steps"`
// LogTail is the last lines of the output of the job's failed steps, led
// by the lines from its first failure when that lies before them; empty
// when no step failed.
LogTail string `json:"logTail,omitempty"`
// LogError says why that output could not be read; the rest stands.
LogError string `json:"logError,omitempty"`
}
JobDetail is one job with its steps and the end of its failed steps' output.
type JobResult ¶ added in v8.157.0
type JobResult struct {
Repository string `json:"repository"`
// Job is absent when CircleCI has no such job.
Job *JobDetail `json:"job,omitempty"`
}
JobResult is the document part of `ci job`.
func NewJobResult ¶ added in v8.157.0
NewJobResult is an empty result for repository.
type JobStep ¶ added in v8.157.0
type JobStep struct {
Name string `json:"name"`
Index int `json:"index"`
Status string `json:"status"`
StartedAt *time.Time `json:"startedAt,omitempty"`
EndedAt *time.Time `json:"endedAt,omitempty"`
}
JobStep is one step of the job, a parallel step once per action.
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.