workflow

package
v1.233.0-rc.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 49 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ControlFailWaitAll    = "wait_all"
	ControlFailFast       = "fail_fast"
	ControlFailBestEffort = "best_effort"

	ControlOutputGrouped  = "grouped"
	ControlOutputPrefixed = "prefixed"
	ControlOutputNone     = "none"

	ControlOutputCompletion = "completion"
	ControlOutputDefinition = "definition"
)

Variables

This section is empty.

Functions

func AppendAtmosStepFlags added in v1.225.0 

func AppendAtmosStepFlags(args []string, flags AtmosStepFlags) []string

AppendAtmosStepFlags inserts workflow command flags before a pass-through separator.

func BuildConditionContext added in v1.223.0 

func BuildConditionContext(workflow string, workflowDefinition *schema.WorkflowDefinition, step *schema.WorkflowStep, commandLineStack string, baseEnv map[string]string) schema.ConditionContext

BuildConditionContext constructs the runtime facts exposed to workflow `when` conditions. Step stack overrides workflow stack, command-line stack overrides both, and step env overlays workflow/base env.

func CalculateWorkingDirectory added in v1.222.0 

func CalculateWorkingDirectory(workflowDef *schema.WorkflowDefinition, step *schema.WorkflowStep, basePath string) string

CalculateWorkingDirectory determines the working directory for a workflow step. Step-level working_directory overrides workflow-level. Relative paths resolve against basePath.

func CancelBackground added in v1.222.0 

func CancelBackground(ctx context.Context, reg *background.Registry, names []string) error

CancelBackground gracefully tears down the named background steps and removes them from the registry so the end-of-scope auto-teardown does not stop them again.

func CheckAndGenerateWorkflowStepNames 

func CheckAndGenerateWorkflowStepNames(workflowDefinition *schema.WorkflowDefinition)

CheckAndGenerateWorkflowStepNames assigns generated names to any workflow steps (and nested steps) that do not declare one, so every step is addressable.

func ExecuteControlStep added in v1.222.0 

func ExecuteControlStep(ctx context.Context, parent *schema.WorkflowStep, executor ControlChildExecutor, opts ControlExecutionOptions) error

func GatePendingBackground added in v1.222.0 

func GatePendingBackground(ctx context.Context, reg *background.Registry, gated map[string]bool) error

GatePendingBackground applies the implicit readiness gate run before each foreground step: it blocks until every registered background step that has not already passed its gate is ready, then records those names in gated so later foreground steps don't re-probe them. A nil/empty registry (or all-gated) is a no-op.

func LoadManifest 

func LoadManifest(atmosConfig *schema.AtmosConfiguration, file string, content []byte) (schema.WorkflowManifest, error)

LoadManifest parses the content of the workflow manifest at file.

Local !include and !include.raw paths resolve the same way wherever Atmos runs from: "./x" and "../x" against the manifest's directory, bare "x/y" against the Atmos project base path, and absolute paths as written. A step whose script comes from such a file records that file in WorkflowStep.ScriptSource, so the script's own load() calls resolve relative to it.

func RenderScriptInterpreter 

func RenderScriptInterpreter(step *schema.WorkflowStep, render func(string) (string, error)) error

RenderScriptInterpreter renders a templated interpreter on a script step in place, so the container checks and the container command see the effective interpreter instead of the raw template. The step must be a copy the caller owns. Non-script steps and plain interpreters are left untouched.

func RunStepContainerOverride added in v1.222.0 

func RunStepContainerOverride(ctx context.Context, params *ContainerStepParams) error

RunStepContainerOverride runs a shell step in a one-shot step-level container.

func StartBackground added in v1.222.0 

func StartBackground(
	ctx context.Context,
	reg *background.Registry,
	runner background.Runner,
	step *schema.WorkflowStep,
	env []string,
) error

StartBackground launches a background step through the runner and registers its handle. Start is non-blocking: it does not wait on readiness, so consecutive background steps come up concurrently. The implicit readiness gate is applied by the workflow executor before the next foreground step (and by `wait`/`wait-all`), reusing the step's health check via Handle.WaitReady.

func StepContainerDisabled added in v1.222.0 

func StepContainerDisabled(step *schema.WorkflowStep) bool

StepContainerDisabled reports whether the step explicitly opts out of the workflow container.

func StepContainerOverride added in v1.222.0 

func StepContainerOverride(step *schema.WorkflowStep) bool

StepContainerOverride reports whether the step has an enabled container override.

func ValidateEmbeddedInterpreterSteps 

func ValidateEmbeddedInterpreterSteps(owner string, ambient *schema.WorkflowContainer, steps []schema.WorkflowStep) error

ValidateEmbeddedInterpreterSteps is the step-list form of ValidateEmbeddedInterpreters. The ambient container is the workflow-level container (nil for custom commands, which only have step-level containers). It recurses into parallel, matrix, and test children.

func ValidateEmbeddedInterpreters 

func ValidateEmbeddedInterpreters(workflowName string, def *schema.WorkflowDefinition) error

ValidateEmbeddedInterpreters rejects, before any step runs, a workflow whose steps would run an embedded interpreter (such as Starlark) under an enabled container. Embedded interpreters run inside the Atmos process, so they cannot execute in a container; without this up-front check the failure only surfaces after earlier steps have already run.

func WaitAllBackground added in v1.222.0 

func WaitAllBackground(ctx context.Context, reg *background.Registry) error

WaitAllBackground blocks until all currently-registered background steps are ready.

func WaitBackground added in v1.222.0 

func WaitBackground(ctx context.Context, reg *background.Registry, names []string) error

WaitBackground blocks until every named background step is ready (a service's health check passes). Names are validated upstream, but a missing name is reported rather than silently ignored.

Types

type AtmosStepFlags added in v1.225.0 

type AtmosStepFlags struct {
	Stack  string
	Tags   []string
	Labels string
}

AtmosStepFlags are command-line flags applied to an Atmos workflow step.

type ContainerRunner added in v1.222.0 

type ContainerRunner struct {
	// Stack scopes the instance label namespace so background steps in different
	// stacks resolve to distinct instances.
	Stack string
	// DryRun skips the actual runtime calls (start/wait/stop become no-ops).
	DryRun bool
}

ContainerRunner starts background container services using Atmos's existing long-lived container lifecycle (Up/WaitHealthy/Down). It implements background.Runner. The container runtime supervises the process, so no goroutine is required.

func (*ContainerRunner) Start added in v1.222.0 

func (cr *ContainerRunner) Start(ctx context.Context, step *schema.WorkflowStep, env []string) (background.Handle, error)

Start launches the background container described by the step's `with:` block (step.Run) detached, and returns a handle that waits on its health check and tears it down.

type ContainerSession added in v1.222.0 

type ContainerSession struct {
	// contains filtered or unexported fields
}

ContainerSession owns the long-lived container backing a workflow run.

func StartWorkflowContainer added in v1.222.0 

func StartWorkflowContainer(ctx context.Context, params *ContainerStepParams) (*ContainerSession, error)

StartWorkflowContainer starts the workflow-level container if configured.

func (*ContainerSession) Cleanup added in v1.222.0 

func (s *ContainerSession) Cleanup(success bool) error

Cleanup removes the workflow container according to policy.

func (*ContainerSession) ExecShell added in v1.222.0 

func (s *ContainerSession) ExecShell(ctx context.Context, params *ContainerStepParams) error

ExecShell runs a shell command inside the workflow container.

type ContainerStepParams added in v1.222.0 

type ContainerStepParams struct {
	Workflow      string
	WorkflowPath  string
	BasePath      string
	WorkflowDef   *schema.WorkflowDefinition
	Step          *schema.WorkflowStep
	HostWorkDir   string
	Command       string
	StepEnv       []string
	RuntimeEnv    []string
	DryRun        bool
	StdoutCapture io.Writer
	StderrCapture io.Writer
}

ContainerStepParams carries workflow and step execution inputs for the workflow container entry points. It keeps the public functions within the argument limit and groups related values together.

type ControlChild added in v1.222.0 

type ControlChild struct {
	Step   schema.WorkflowStep
	Matrix map[string]string
}

type ControlChildExecutor added in v1.222.0 

type ControlChildExecutor func(ctx context.Context, child *ControlChild, output ControlChildOutput) (*ControlChildResult, error)

type ControlChildOutput added in v1.222.0 

type ControlChildOutput struct {
	Mode   string
	Prefix string
}

type ControlChildResult added in v1.222.0 

type ControlChildResult struct {
	Stdout   string
	Stderr   string
	Canceled bool
	// Value overrides stdout for interpreters with structured output.
	Value *string
}

type ControlCommandExecutor added in v1.222.0 

type ControlCommandExecutor struct {
	// DryRun makes the executor execute nothing. Children that run through RunCommand
	// (atmos, shell without a ShellRunner, external script) are still dispatched with
	// ControlCommandRequest.DryRun set, so the runner owns the dry-run behavior (the
	// workflow runner emits its dry-run diagnostics there). Children with no dry-run-aware
	// runner (a ShellRunner shell child and every embedded script child) are skipped here,
	// before any runner or embedded engine is reached.
	DryRun bool
	// ScriptHook supplies host-owned lifecycle facts to embedded script children.
	ScriptHook *script.HookContext
	// ScriptComponent is the component the enclosing execution context is scoped
	// to. Embedded script children expose it as `ctx.component`.
	ScriptComponent *script.ComponentRef
	// ScriptFlags and ScriptArguments retain parsed invocation values for child scripts.
	ScriptFlags, ScriptArguments map[string]any
	// ResolveComponent backs `components.get` in embedded script children.
	ResolveComponent script.ComponentResolver
	InstallTools     script.ToolInstaller
	// CI reports into the active CI provider for embedded script children and renders locally
	// when none is detected. Hosts construct it with ci.NewReporter; nil means a local-only reporter.
	CI          ci.Reporter
	ScriptSteps automation.StepLibrary
	// ProjectRoot is the absolute Atmos project base path. Embedded script children show paths under
	// it relative to it in errors and tracebacks.
	ProjectRoot string
	// ScriptProcessOverrides names the env keys whose values take precedence over
	// component env for component processes (command-level env). The values are
	// refreshed from each child's final process env at execution time.
	ScriptProcessOverrides map[string]string

	WorkflowDefinition  *schema.WorkflowDefinition
	BasePath            string
	BaseEnv             []string
	CommandLineStack    string
	CommandLineTags     []string
	CommandLineLabels   string
	CommandLineIdentity string
	PrepareEnv          ControlEnvironmentFunc
	RunCommand          ControlCommandRunner
	ShellRunner         ControlShellRunner
	// contains filtered or unexported fields
}

func (*ControlCommandExecutor) Execute added in v1.222.0 

func (executor *ControlCommandExecutor) Execute(ctx context.Context, child *ControlChild, output ControlChildOutput) (*ControlChildResult, error)

type ControlCommandRequest added in v1.222.0 

type ControlCommandRequest struct {
	// DryRun asks the runner to report the command without executing it.
	DryRun  bool
	Context context.Context
	Program string
	Args    []string
	Dir     string
	Env     []string
	Streams process.Streams
	Stdout  *bytes.Buffer
	Stderr  *bytes.Buffer
}

type ControlCommandRunner added in v1.222.0 

type ControlCommandRunner func(request *ControlCommandRequest) error

type ControlEnvironmentFunc added in v1.222.0 

type ControlEnvironmentFunc func(baseEnv []string, identity string, stepName string, workflowEnv map[string]string, stepEnv map[string]string) ([]string, error)

type ControlExecutionOptions added in v1.222.0 

type ControlExecutionOptions struct {
	TemplateData ControlTemplateDataFunc
	// RenderTemplate renders each child's template fields. Callers set it to the parent context's
	// renderer so children see the same template functions and pass count as sequential steps. When
	// nil, children render with plain text/template.
	RenderTemplate ControlRenderFunc
	StoreResult    ControlStoreResultFunc
}

type ControlRenderFunc 

type ControlRenderFunc func(name, input string, data map[string]any) (string, error)

ControlRenderFunc renders one template string against data. It lets a parallel or matrix step render its children with the same renderer, function set, and pass count as the context the parent step runs in.

type ControlResult added in v1.222.0 

type ControlResult struct {
	Name      string
	Stdout    string
	Stderr    string
	Status    string
	Err       error
	Canceled  bool
	Completed int64
	Value     *string
}

type ControlShellRequest added in v1.223.0 

type ControlShellRequest struct {
	Command string
	Dir     string
	Env     []string
	Stdout  io.Writer
	Stderr  io.Writer
}

ControlShellRequest carries the inputs for a control shell child's execution.

type ControlShellRunner added in v1.223.0 

type ControlShellRunner func(ctx context.Context, req *ControlShellRequest) error

ControlShellRunner executes a `type: shell` child's command string. When set on a ControlCommandExecutor it replaces the host `sh -c` / `RunCommand` path so shell children run through the in-process mvdan/sh interpreter (cross-platform, masked, cancellable). The workflow executor leaves it nil to keep its auth-aware RunCommand path; the registry bridge sets it.

type ControlStoreResultFunc added in v1.222.0 

type ControlStoreResultFunc func(result *scheduler.Result)

type ControlTemplateDataFunc added in v1.222.0 

type ControlTemplateDataFunc func(stepName string, matrix map[string]string) map[string]any

type ProgressRenderer added in v1.221.0 

type ProgressRenderer struct {
	// contains filtered or unexported fields
}

ProgressRenderer handles progress bar rendering for workflow execution. It displays a right-aligned progress bar showing step completion status. Each step gets its own progress line showing current position in the workflow.

func NewProgressRenderer added in v1.221.0 

func NewProgressRenderer(workflow *schema.WorkflowDefinition, totalSteps int) *ProgressRenderer

NewProgressRenderer creates a new progress renderer for workflow execution. Returns nil if progress display is disabled or terminal doesn't support TTY.

func (*ProgressRenderer) Done added in v1.221.0 

func (r *ProgressRenderer) Done()

Done marks the progress as complete. This can be used to clean up or render a final state.

func (*ProgressRenderer) IsEnabled added in v1.221.0 

func (r *ProgressRenderer) IsEnabled() bool

IsEnabled returns whether progress rendering is enabled.

func (*ProgressRenderer) Render deprecated added in v1.221.0 

func (r *ProgressRenderer) Render()

Render renders the progress bar with just the step name on the left. Format: stepName ... [████░░░] n/m

Deprecated: Use RenderWithLabel for combined step label + progress.

func (*ProgressRenderer) RenderPermanent added in v1.221.0 

func (r *ProgressRenderer) RenderPermanent(stepLabel string)

RenderPermanent renders the progress bar WITH newline as a permanent record. Call this after step execution completes to preserve the progress line.

func (*ProgressRenderer) RenderWithLabel added in v1.221.0 

func (r *ProgressRenderer) RenderWithLabel(stepLabel string)

RenderWithLabel renders the progress bar with the step label on the left. Format: 1/5 stepname ... [████░░░] n/m Renders WITHOUT newline for in-place display. Call ui.ClearLine() before any step output, then RenderPermanent() after step completes.

func (*ProgressRenderer) Update added in v1.221.0 

func (r *ProgressRenderer) Update(current int, stepName string)

Update updates the progress to the current step.

type ShowRenderer added in v1.221.0 

type ShowRenderer struct {
	// contains filtered or unexported fields
}

ShowRenderer handles rendering of show features for workflows.

func NewShowRenderer added in v1.221.0 

func NewShowRenderer() *ShowRenderer

NewShowRenderer creates a new ShowRenderer.

func (*ShowRenderer) RenderHeaderIfNeeded added in v1.221.0 

func (r *ShowRenderer) RenderHeaderIfNeeded(
	workflow *schema.WorkflowDefinition,
	workflowName string,
	flags map[string]string,
)

RenderHeaderIfNeeded renders the workflow header and flags if configured and not already rendered. This should be called before the first step executes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.