1// SPDX-License-Identifier: MIT
2
3package executor
4
5import "time"
6
7// Conclusion is how a step or a job ended, with the names of the protocol
8// (CiConclusion in ermite-api).
9type Conclusion string
10
11// Conclusions.
12const (
13 ConclusionSuccess Conclusion = "success"
14 ConclusionFailure Conclusion = "failure"
15 ConclusionCancelled Conclusion = "cancelled"
16 ConclusionSkipped Conclusion = "skipped"
17 ConclusionTimedOut Conclusion = "timed_out" // jobs only
18)
19
20// Reporter receives what happens in a job. The executor calls it from several
21// goroutines but never concurrently: calls are serialised.
22//
23// Steps are numbered like GitHub's log: "Set up job" is 1, the steps of the
24// workflow follow, and "Complete job" is last. Every log line belongs to the
25// step that is running.
26type Reporter interface {
27 // StepStarted announces a step that begins to run, with its display name.
28 // A step skipped by its condition gets StepStarted and StepCompleted too.
29 StepStarted(number int, name string, at time.Time)
30 // Log is one line of the job log, without its line terminator.
31 Log(number int, at time.Time, line string)
32 // StepCompleted ends a step.
33 StepCompleted(number int, name string, conclusion Conclusion, at time.Time)
34 // JobCompleted is the last call: the result of the job.
35 JobCompleted(Result)
36}
37
38// Result is the outcome of a job.
39type Result struct {
40 Conclusion Conclusion
41 // Outputs are the job outputs, evaluated at the end of the job. Empty values
42 // are left out, like the official runner does.
43 Outputs map[string]string
44 // Error is a job-level error (a timeout, a workflow that cannot be run);
45 // step errors are in the log.
46 Error string
47 // RunnerShutdown is true when the job was cut short because the runner was
48 // told to stop (see ErrShutdown).
49 RunnerShutdown bool
50}
51
52// AnnotationLevel is the severity of an annotation.
53type AnnotationLevel string
54
55// Levels, with the names of GitHub's check run annotations.
56const (
57 LevelNotice AnnotationLevel = "notice"
58 LevelWarning AnnotationLevel = "warning"
59 LevelFailure AnnotationLevel = "failure" // ::error and an error that the runner itself logs
60)
61
62// Annotation is a message attached to a step, produced by ::notice,
63// ::warning, ::error, a problem matcher or an error the runner logs, and
64// already masked. The executor keeps at most 10 per level per step.
65type Annotation struct {
66 Level AnnotationLevel
67 Title, Message, File string
68 StartLine, EndLine int32
69 StartColumn int32
70 EndColumn int32
71}
72
73// StepResults is what a step leaves besides its log, reported just before
74// StepCompleted.
75type StepResults struct {
76 // Outcome is steps.<id>.outcome: the result before continue-on-error.
77 Outcome Conclusion
78 // Annotations is the whole list of the step, replacing any earlier one. It
79 // is empty when ci.annotations is not available (Config.SendAnnotations).
80 Annotations []Annotation
81 // Summary is the masked GITHUB_STEP_SUMMARY of the step, HasSummary says
82 // whether there is one. Empty when ci.summaries is not available
83 // (Config.SendSummaries).
84 Summary string
85 HasSummary bool
86}
87
88// StepResultReporter is implemented by a Reporter that wants the results of
89// the steps. StepResults(n) is called once for each step of the workflow,
90// before StepCompleted(n) and under the same serialisation.
91type StepResultReporter interface {
92 StepResults(number int, r StepResults)
93}