Workflow Declaration

Workflow Declaration

workflow("build", {
    { phase = "generate", scope = "code" },
    { phase = "compile",  scope = "code" },
})

A workflow is an ordered list of workflow steps. Each workflow step runs one or more phase+scope pairs.

See also: Plugin System for staged workflows, importing workflows from plugins (workflows({ build = "coditary/pipeline:build" })), and phase[scope] syntax.

Sequential steps

workflow("build", {
    { phase = "generate", scope = "code" },
    { phase = "compile",  scope = "code" },
    { phase = "test",     scope = "unit" },
})

Beez runs each entry after the previous one finishes.

For { phase = "compile", scope = "code" }, Beez runs all steps where step.phase == "compile" and step.scope == "code", using order() and parallelism rules inside that group.

Parallel workflow step

workflow("ci", {
    { parallel = {
        { phase = "generate", scope = "docs" },
        { phase = "generate", scope = "code" },
    }},
    { phase = "compile", scope = "code" },
})

The parallel table contains phase+scope entries that run at the same time. The next workflow step waits until all parallel branches complete.

Each parallel entry must be a table with:

Field	Required	Type
phase	yes	string
scope	yes	string

parallel must contain at least one entry.

Staged workflows (recommended for pipelines)

Group phase+scope invocations into named stages. Stages run sequentially; invocations inside a stage run in parallel.

workflows {
    build = {
        { "setup",   { "setup[app]" } },
        { "compile", { "compile[app]" } },
        { "bundle",  { "bundle[app]" } },
        { "test",    { "test[test]" } },
    },
}

Syntax in invocation list	Meaning
"compile[app]"	Phase compile, scope app
"setup"	Phase setup, all scopes

Import a plugin workflow in build.lua:

workflows({
    all = "coditary/pipeline:all",
})

Do not mix staged entries ({ "stage", { ... } }) with legacy { phase, scope } tables in the same workflow.

Import multiple workflows

workflows({
    build   = "coditary/pipeline:build",
    quality = "coditary/pipeline:quality",
    quick   = {
        { "test", { "test[test]" } },
    },
})

Workflow step forms

Form	Meaning
{ phase = "p", scope = "s" }	Run one phase+scope
{ parallel = { { phase, scope }, ... } }	Run several phase+scope pairs in parallel

Non-table entries in the workflow list are ignored.

What workflows do not contain

• Shell commands (use a task or a step with run string)
• Direct step names (use a task like { name = "step" } or run beez -s)
• Nested workflows

Invocation

beez build
beez ci

See Running Targets.

Designing workflows

Workflows are entry points for pipelines. Common patterns:

• build - compile and maybe test
• ci - lint, test, package
• check - fast validation subset

Name and structure are entirely up to you. Beez does not ship built-in workflow names.

Full example

step({
    name = "gen-docs",
    phase = "generate",
    scope = "docs",
    run = "make docs",
})
step({
    name = "gen-code",
    phase = "generate",
    scope = "code",
    run = "make codegen",
})
step({
    name = "compile",
    phase = "compile",
    scope = "code",
    run = "make",
})

order("gen-code", "compile")

workflow("ci", {
    { parallel = {
        { phase = "generate", scope = "docs" },
        { phase = "generate", scope = "code" },
    }},
    { phase = "compile", scope = "code" },
})

Next steps

• Order Declaration - ordering inside a phase+scope
• Parallel Execution and Dependencies - how steps run inside each block
• Filtering by Phase - run a phase without a workflow