flowascode

README

flow as code

create a flow as code (in YAML format) is a utility that executes workflows based on a yaml configuration you pass in.

Sample flow document: documentation/example-flow.yaml

Remarks: the example document still communicates features not yet implemented

Usage

flow-as-code --flow <flow.yaml> --name <test> [--debug]


--flow      path to the file containing the flow definition
--name      name of the step to execute (entrypoint)
--log-level set log level (one of debug, info, warn or error[default])

Configuration

The configuration is done using a YAML document. It has the following structure:

---

shell:       string      # binary in path or complete path to
                         # shell that will be called

name:        string      # just give the thing a name
description: string      # provide a more in depth description

steps:       list        # provide a list of steps

A step contains the following properties:

name:        string      # just give the thing a name
on_success:  list        # follow up with steps on success (descendant)
on failure:  list        # follow up with steps on failure (descendant)
script:      list        # list of commands to execute

A descendant contains the following properties:

name:        string      # must match the name of a step
variables:   map         # A dictionary (map) of variables passed to
                         # the step to be executed

Variable handling

The variables get special treatment as $VAR gets replaced by the environment variable named VAR.

Also you can access the flow and the current step like this:

{{.Flow.Name}}        # Name
{{.Flow.Shell}}       # Shell
{{.Flow.Description}} # Description
{{.Flow.Steps}}       # All steps

{{.Step.Name}}        # Name
{{.Step.Script}}      # Commands to be executed
{{.Step.OnSuccess}}   # List of descendants on success
{{.Step.OnFailure}}   # List of descendants on failure

History

Version	Description
0.3.0	- support for templated variables
	- add --log-level parameter
	- make use of dependabot
0.2.0	- support to pass variables to descendants
	- license and contributor information
	- integrated gops
0.1.0	initial minimal version

Documentation

Index

• Constants
• func SetLogLevel(level logrus.Level)
• type Descendant
• type Error
  • func (e Error) Error() string
• type Flow
  • func NewFromReader(reader io.Reader) (*Flow, error)
  • func NewFromYAML(data string) (*Flow, error)
  • func (f *Flow) Execute(name string, variables map[string]string) error
  • func (f *Flow) GetDefault() (*Step, error)
  • func (f *Flow) GetStep(name string) (*Step, error)
  • func (f *Flow) HasDefault() bool
  • func (f *Flow) HasStep(name string) bool
  • func (f Flow) String() string
  • func (f *Flow) ValidateStep(name string) error
• type Step
  • func (s *Step) Execute(pathToShell string, variables []string) error
  • func (s *Step) HasFailure() bool
  • func (s *Step) HasSuccess() bool
  • func (s Step) String() string

Constants

const ErrMissingFailureStep = Error("failure step not defined")

const ErrMissingStep = Error("step not defined")

const ErrMissingSuccessStep = Error("success step not defined")

const ErrNoScript = Error("no script in step")

Functions

func SetLogLevel

func SetLogLevel(level logrus.Level)

SetLogLevel can be used to adjust the log level

Types

type Descendant

type Descendant struct {
	Name      string            `yaml:"name"`      // Name is the referenced step
	Variables map[string]string `yaml:"variables"` // Variables is a list of variables that are set as environment variables
}

Descendant represents on step after the current step that is it is a reference to a number of other steps

type Error

type Error string

Error type for constant error definitions

func (Error) Error

func (e Error) Error() string

type Flow

type Flow struct {
	// BreakOnError bool   `yaml:"break_on_error"` // BreakOnError breaks if a script returns a non zero result
	Name        string `yaml:"name"`        // Name is a name for the flow
	Description string `yaml:"description"` // Description is a more descriptive text what the flow does
	Steps       []Step `yaml:"steps"`       // Steps is the collection of steps in the flow
	Shell       string `yaml:"shell"`       // Shell is the path or binary name for the shell to use to execute the script
}

Flow represents a complete flow

func NewFromReader

func NewFromReader(reader io.Reader) (*Flow, error)

NewFromReader creates a Flow from a reader

func NewFromYAML

func NewFromYAML(data string) (*Flow, error)

NewFromYAML takes a yaml string and creates a Flow object

func (*Flow) Execute

func (f *Flow) Execute(name string, variables map[string]string) error

Execute takes a step name and starts to execute from there if no ma,e is given it tries to get the default namespace

func (*Flow) GetDefault

func (f *Flow) GetDefault() (*Step, error)

GetDefault returns the default step

func (*Flow) GetStep

func (f *Flow) GetStep(name string) (*Step, error)

GetStep returns the named step if found

func (*Flow) HasDefault

func (f *Flow) HasDefault() bool

HasDefault returns true if there is a default step

A default step gets executed when no step is defined

func (*Flow) HasStep

func (f *Flow) HasStep(name string) bool

HasStep returns true in case the step exists

func (Flow) String

func (f Flow) String() string

String method is used to print values passed as an operand

func (*Flow) ValidateStep

func (f *Flow) ValidateStep(name string) error

ValidateStep looks if a step could run successful

type Step

type Step struct {
	Name      string       `yaml:"name"`       // Name of a step, also used to reference from C(Descendant)
	Script    []string     `yaml:"script"`     // Script to execute
	OnSuccess []Descendant `yaml:"on_success"` // OnSuccess is a list of steps to execute if the script returns with 0
	OnFailure []Descendant `yaml:"on_failure"` // OnFailure is a list of steps to execute if the scripts returns not a 0
}

Step is a single execution point in a flow

func (*Step) Execute

func (s *Step) Execute(pathToShell string, variables []string) error

Execute is going to execute the script calls os specific implementations

func (*Step) HasFailure

func (s *Step) HasFailure() bool

HasFailure returns true if there are further steps in case of a non successful run defined

func (*Step) HasSuccess

func (s *Step) HasSuccess() bool

HasSuccess returns true if there are further steps in case of a successful run defined

func (Step) String

func (s Step) String() string

String method is used to print values passed as an operand