Skip to main content

Step System

Pipeline Step System

Internal API

Understand the internal contracts a contributor must preserve when adding or changing pipeline behavior.

Commandapp/core/pipeline/

Category

Developer Guide

Quick Command

resolve → create registered steps → execute(context)
BaseStepStepRegistryPipelineBuilderGitContext

Overview​

Custy's pipeline package separates workflow definition from execution. Profiles name the intended steps, the registry maps names to classes, the builder creates instances, and the pipeline invokes each instance with one shared context.

Core Responsibilities

Pipeline Building Blocks

BaseStep

Defines the required execute(context) interface for every step.

StepRegistry

Maps a unique string name to a step class and creates instances on demand.

Step Registration

Registers Custy's built-in validation, preparation, generation, backup, cleanup, execution, and finalization steps.

CommandResolver

Expands profiles and normalizes multi-profile composition before building begins.

PipelineBuilder

Converts resolved step dictionaries into concrete objects through the registry.

GitContext

Carries the workflow engine, shared services, and mutable runtime values across steps.

Source Map

  • app/core/pipeline/profiles.py — profile definitions and global phase order.
  • app/core/pipeline/command_resolver.py — expansion, cycle detection, deduplication, and ordering.
  • app/core/pipeline/registry.py — name-to-class storage and instance creation.
  • app/core/pipeline/step_registry.py — one-time built-in registration.
  • app/core/pipeline/builder.py — progress and simple pipeline construction.
  • app/core/pipeline/pipeline.py — sequential execution and failure reporting.
  • app/core/pipeline/context.py — the shared runtime contract.
  • app/core/pipeline/steps/ — concrete step adapters.
  • app/core/workflow/workflow_engine.py — active workflow operations invoked by most steps.

Contributor Checklist

Before You Begin

  • Implement one focused stepRequired

    Subclass BaseStep and provide a documented execute(context) method with one clear responsibility.

  • Register a unique nameRequired

    Add the class to register_all_steps(); duplicate names raise ValueError.

  • Assign phase orderRequired

    Add the name to STEP_ORDER so merged profiles cannot place it in an unsafe phase.

  • Add it to intentional profilesRequired

    Update only profiles that truly require the new behavior; do not hide profile logic in the resolver.

  • Test resolution and executionRequired

    Cover profile membership, ordering, deduplication, failure behavior, and the expected engine call.

  • Update user and developer docsRequired

    Document changed requirements, side effects, output, recovery, and extension behavior.

Registry Contracts

  • Call register_all_steps() once before building a pipeline. Registering the same name again raises ValueError.
  • Building an unregistered name fails with KeyError before execution.
  • Step constructor arguments may be supplied through an args object in a resolved step definition.
  • Registration only makes a class buildable; it does not expose a new public custy run profile name.

Context and State Discipline

Keep configuration and services in the workflow engine. Use GitContext for shared runtime state that must cross a step boundary, such as the current tag, workflow case, or staging list. A step should delegate domain behavior to the engine or a focused service instead of duplicating Git or release logic.

Every step that can participate in merged profiles should have an explicit STEP_ORDER entry. Without one, it receives fallback priority 999 and moves behind all known steps. Review the complete contract in Step Priority and Ordering.

Continue

Related Commands

Commands commonly used together with this command.