Skip to main content

Workflow Engine

Workflow Engine

Central Application Service

Inspect the application facade that registered steps use for release, Git, changelog, backup, and branch behavior.

Commandapp/core/workflow/

Category

Architecture

Quick Command

resolved args -> WorkflowConfig -> builder -> WorkflowEngine
builderfacaderuntime stateservices
Input Model
WorkflowConfig
Construction
WorkflowEngineBuilder
Facade
WorkflowEngine
Primary Caller
Pipeline steps

Overview​

The workflow package turns resolved command arguments into one engine that owns the services and mutable release state needed by pipeline steps. A step is usually a thin adapter whose execute() method calls one engine method.

Construction Model

WorkflowConfig

workflow_config.py

A dataclass containing commit, tag, version, execution, file, staging, force, remote, backup, and retention inputs used to construct an engine.

WorkflowEngineBuilder

workflow_builder.py

Offers fluent setters, maps supported attributes from resolved command models, validates configuration relationships, and creates the engine.

WorkflowEngine

workflow_engine.py

Copies construction input into runtime fields, creates shared services, holds the active tag and staging state, and exposes one method per workflow phase.

GitContext

pipeline/context.py

Wraps the engine for pipeline execution and exposes its Git service plus optional cross-step fields. Active steps primarily delegate to engine state.

Constructed Services

WorkflowEngine Service Graph

WorkflowEngine→GitService

Repository inspection, staging, commit, tag, push, history, branches, and remotes.

WorkflowEngine→CommitizenHelper

Commit-convention checks and Commitizen-related version behavior.

WorkflowEngine→ChangelogGenerator

Collect, transform, render, and write changelog content.

WorkflowEngine→BackupManager

Create retained commit and tag message backups.

WorkflowEngine→BranchWorkflowManager

Coordinate initial and final branch transitions.

Engine Phase Families

Workflow Timeline

1
Validate
Check repository, remotes, files, staged state, and commit conventions.
completed
2
Prepare
Resolve the tag, initialize branch policy, and prepare release messages.
completed
3
Generate and review
Create artifacts, open files for editing, and validate edited content.
completed
4
Apply release content
Update supported project versions and conditionally generate the changelog.
completed
5
Protect and commit
Back up messages, prune retained files, stage changes, and create a commit.
current
6
Publish and finalize
Create the tag, push selected remotes, and optionally execute experimental branch finalization.
pending

Two Orchestration Styles

The active CLI normally uses pipeline profiles whose individual steps call phase methods on the engine. WorkflowEngine.run() also contains a complete hard-coded release sequence, but public Run behavior is defined by PIPELINE_PROFILES, the resolver, and registered steps. Contributors should not assume that changing run() changes custy run release.

State and Failure Boundaries

  • The engine holds mutable tag, tag-message, workflow-case, and staged-file state across phase calls.
  • GitContext references the same engine and Git service; active steps mostly use engine-owned state rather than copying values into context fields.
  • Engine methods convert many service failures into actionable ValidationError instances, but the pipeline re-raises and stops.
  • The engine does not record a transaction log or compensation plan, so a later failure does not reverse earlier effects.
  • Dry-run checks exist both in workflow methods and lower-level runner-backed services, but reads, validation, resolution, and prompts can still occur.

Continue

Related Commands

Commands commonly used together with this command.

Git Operations

Inspect the main repository service consumed by the engine.

Changelog System

Follow conditional changelog generation through its internal pipeline.