pipeline

type Action ¶

type Action func(context.Context, ActionOpts) error

Action is the function signature that a step provides when it does something.

var DefaultAction Action = nil

type ActionOpts ¶

type ActionOpts struct {
	State  state.Handler
	Stdout io.Writer
	Stderr io.Writer
	Tracer opentracing.Tracer
	Logger logrus.FieldLogger

	// Path is the path to the pipeline, typically provided via the `-path` argument, but automatically supplied if using the scribe CLI.
	Path string
	// Version refers to the version of Scribe that was used to run the pipeline.
	// This value is set using the `-version` argument when running a pipeline, which is automatically set by the `scribe` command.
	Version string
}

The ActionOpts are provided to every step that is ran. Each step can choose to use these options.

type CacheCondition ¶

type CacheCondition func() bool

a CacheCondition should return true if the cacher should cache the step. In other words, returning false means that the step must run.

type Cacher ¶

type Cacher func(Step)

A Cacher defines behavior for caching data. Some behaviors that can happen when dealing with a cacheable step: * The provided Step, using an expensive process, produces some consistent output, possibly on the filesystem. If nothing changes in between runs, then we can re-use the output in the current step and skip this one.

• The most common example of this is `npm install` producing the `node_modules` folder, which can be re-used if `package-lock.json` is unchanged.

* The provided Step, using an expensive process, calculates a value. If nothing changes in between runs, then this value can be reused.

type Client ¶

type Client interface {
	// Validate is ran internally before calling Run or Parallel and allows the client to effectively configure per-step requirements
	// For example, Drone steps MUST have an image so the Drone client returns an error in this function when the provided step does not have an image.
	// If the error encountered is not critical but should still be logged, then return a plumbing.ErrorSkipValidation.
	// The error is checked with `errors.Is` so the error can be wrapped with fmt.Errorf.
	Validate(Step) error

	// Done must be ran at the end of the pipeline.
	// This is typically what takes the defined pipeline steps, runs them in the order defined, and produces some kind of output.
	Done(context.Context, *Collection) error
}

type Collection ¶

type Collection struct {
	Graph     *dag.Graph[Pipeline]
	Providers map[state.Argument]int64
	Root      []int64
}

Collection defines a directed acyclic Graph that stores a collection of Steps. When using Scribe with "scribe.New", this collection contains a graph with one pipeline in it. When using Scribe with "scribe.NewMulti", this collection contains a graph with several pipelines in it.

func NewCollection() *Collection

func NewCollectionWithSteps(pipelineName string, steps ...Step) (*Collection, error)

func (c *Collection) AddEvents(pipelineID int64, events ...Event) error

func (c *Collection) AddPipelines(pipelines ...Pipeline) error

func (c *Collection) AddSteps(pipelineID int64, steps ...Step) error

func (c *Collection) BuildEdges(log logrus.FieldLogger, rootArgs ...state.Argument) error

func (c *Collection) ByID(ctx context.Context, id int64) (Step, error)

func (c *Collection) ByName(ctx context.Context, name string) ([]Step, error)

func (c *Collection) PipelinesByEvent(ctx context.Context, name string) ([]Pipeline, error)

func (c *Collection) PipelinesByName(ctx context.Context, names []string) ([]Pipeline, error)

func (c *Collection) SetProvider(arg state.Argument, id int64) error

func (c *Collection) WalkPipelines(ctx context.Context, wf PipelineWalkFunc) error

func (c *Collection) WalkSteps(ctx context.Context, pipelineID int64, wf StepWalkFunc) error

type Configurer ¶

type Configurer interface {
	// Value returns the implementation-specific pipeline config.
	Value(state.Argument) (string, error)
}

Configurer defines how clients can retrieve configuration values for use in pipelines. For example, a `clone` step might require a remote URL and branch, but how that data is retrieved can change depending on the environment. * In Drone, the value is retrieved from an environment variable at runtime. So the only thing this funcion will likely return is the name of the environment variable. * With the Dagger and CLI clients, the remote URL might be provided as a CLI argument or requested via stdin, or even already available with the `git remote` command.

type EnvVar ¶

type EnvVar struct {
	Type EnvVarType
	// contains filtered or unexported fields
}

func NewEnvArgument(arg state.Argument) EnvVar

func NewEnvString(val string) EnvVar

func (e EnvVar) Argument() state.Argument

func (e EnvVar) String() string

type EnvVarType ¶

type EnvVarType int

const (
	// EnvVarString should be used whenever the value is known and static.
	EnvVarString EnvVarType = iota

	// EnvVarArgument means that the environment variable will be populated by an argument from the state at run-time.
	// Most (all?) CI services will then leave these values out of the configuration and will be injected when the step runs.
	EnvVarArgument
)

type Event ¶

type Event struct {
	Name     string
	Filters  map[string]*FilterValue
	Provides []state.Argument
}

Event is provided when defining a Scribe pipeline to define the events that cause the pipeline to be ran. Some example events that might cause pipelines to be created: * Manual events with user input, like 'Promotions' in Drone. In this scenario, the user may have the ability to supply any keys/values as arguments, however, pipeline developers in Scribe should be able to specifically define what fields are accepted. See https://docs.drone.io/promote/. * git and SCM-related events like 'Pull Reuqest', 'Commit', 'Tag'. Each one of these events has a unique set of arguments / filters. `Commit` may allow pipeline developers to filter by branch or message. Tags may allow developers to filter by name. * cron events, which may allow the pipeline in the CI service to be ran on a schedule. The Event type stores both the filters and a list of values that it provides to the pipeline. Client implementations of the pipeline (type Client) are expected to handle events that they are capable of handling. 'Handling' events means that the the arguments in the `Provides` key should be available before any first steps are ran. It will not typically be up to pipeline developers to decide what arguments an event provides. The only case where this may happen is if the event is a manual one, where users are able to submit the event with any arbitrary set of keys/values. The 'Filters' key is provided in the pipeline code and should not be populated when pre-defined in the Scribe package.

func GitCommitEvent(filters GitCommitFilters) Event

func GitTagEvent(filters GitTagFilters) Event

func PullRequestEvent(filters PullRequestFilters) Event

type FilterValue ¶

type FilterValue struct {
	Type  FilterValueType
	Value fmt.Stringer
}

func GlobFilter(v string) *FilterValue

func RegexpFilter(v *regexp.Regexp) *FilterValue

func StringFilter(v string) *FilterValue

func (f *FilterValue) String() string

type FilterValueType ¶

type FilterValueType int

FilterValueType is the metadata type that identifies the type present event filter.

const (
	FilterValueString FilterValueType = iota
	FilterValueRegex
	FilterValueGlob
)

type GitCommitFilters ¶

type GitCommitFilters struct {
	Branch *FilterValue
}

type GitTagFilters ¶

type GitTagFilters struct {
	Name *FilterValue
}

type Output ¶

type Output interface{}

type Pipeline ¶

type Pipeline struct {
	ID   int64
	Name string
	// Graph is a graph where each node is a list of Steps. Each set of steps runs in parallel.
	Graph     *dag.Graph[Step]
	Providers map[state.Argument]int64
	Root      []int64
	Events    []Event
	Type      PipelineType

	RequiredArgs state.Arguments
	ProvidedArgs state.Arguments
}

A Pipeline is really similar to a Step, except that it contains a graph of steps rather than a single action. Just like a Step, it has dependencies, a name, an ID, etc.

func AdjNodesToPipelines(nodes []*dag.Node[Pipeline]) []Pipeline

func New(name string, id int64) Pipeline

func (p *Pipeline) AddSteps(steps ...Step) error

func (p Pipeline) BuildEdges(rootArgs ...state.Argument) error

func (p Pipeline) Provides(args ...state.Argument) Pipeline

func (p Pipeline) Requires(args ...state.Argument) Pipeline

func (p Pipeline) SetProvider(arg state.Argument, id int64) error

type PipelineType ¶

type PipelineType int

const (
	PipelineTypeDefault PipelineType = iota
	PipelineTypeSub
)

type PipelineWalkFunc ¶

type PipelineWalkFunc func(context.Context, Pipeline) error

PipelineWalkFunc is implemented by the pipeline 'Clients'. This function is executed for each pipeline. This function follows the same rules for pipelines as the StepWalker func does for pipelines. If multiple pipelines are provided in the steps argument, then those pipelines are intended to be executed in parallel.

type PullRequestFilters ¶

type PullRequestFilters struct{}

type Step ¶

type Step struct {
	// ID is the unique number that represents this step.
	// This value is used when calling `scribe -step={serial} [pipeline]`
	ID int64

	// Type represents the how the step is intended to operate. 90% of the time, the default type should be a sufficient descriptor of a step.
	// However in some circumstances, clients may want to handle a step differently based on how it's defined.
	// Background steps, for example, have to have their lifecycles handled differently.
	Type StepType

	// Name is a string that represents or describes the step, essentially the identifier.
	// Not all clients will support using the name for anything beyond logging.
	Name string

	// Image is an optional value that can be assigned to a step.
	// Typically, in docker environments (or drone with a Docker executor), it defines the docker image that is used to run the step.
	Image string

	// Action defines the action this step performs.
	Action Action

	// RequiredArgs are arguments that are must exist in order for this step to run.
	RequiredArgs state.Arguments

	// Provides are arguments that this step provides for other arguments to use in their "Arguments" list.
	ProvidedArgs state.Arguments

	Environment StepEnv
}

A Step stores a Action and a name for use in pipelines. A Step can consist of either a single action or represent a list of actions.

func Combine(step ...Step) Step

func NamedStep(name string, action Action) Step

func NewStep(action Action) Step

func (s Step) IsBackground() bool

func (s Step) Provides(arg ...state.Argument) Step

func (s Step) Requires(args ...state.Argument) Step

func (s Step) ResetArguments() Step

func (s Step) WithEnvVar(key string, val EnvVar) Step

func (s Step) WithEnvironment(env StepEnv) Step

func (s Step) WithImage(image string) Step

func (s Step) WithName(name string) Step

type StepEnv ¶

type StepEnv map[string]EnvVar

type StepType ¶

type StepType int

const (
	StepTypeDefault StepType = iota
	StepTypeBackground
)

type StepWalkFunc ¶

type StepWalkFunc func(context.Context, Step) error

WalkFunc is implemented by the pipeline 'Clients'. This function is executed for each Step.

type Stringer ¶

type Stringer string

func (s Stringer) String() string