pipeline-model-architecture_skill

Overview

This skill explains the BK-CI pipeline core Model architecture and how the four-layer Pipeline/Stage/Container/Task structure is organized. It highlights model serialization, versioning, validation, and runtime fields so developers can understand, extend, and transform pipeline models safely. The content focuses on practical guidance for reading, modifying, and persisting pipeline models in Kotlin-based services.

How this skill works

The skill inspects the pipeline Model as a tree: Model -> Stage[] -> Container[] -> Element[] and explains polymorphic Container/Element implementations with JSON type metadata for serialization. It covers where runtime-only fields live, how version compatibility and deprecated fields are handled, and common utility methods (trigger container access, task counting, element removal, default model factory). It also describes Stage/Container control options, matrix expansion, and job execution controls.

When to use it

• Design or review pipeline data structures for CI/CD features
• Implement serialization/deserialization or JSON compatibility logic
• Add or remove plugin task types from pipeline templates
• Implement versioning, model migration, or snapshot storage
• Debug runtime build behavior or field population issues

Best practices

• Treat Model as the single source of truth for pipeline configuration and snapshots
• Keep runtime-only fields (status, executeCount) separate from persisted config fields
• Use JsonTypeInfo/JsonSubTypes for polymorphic serialization and include transformCompatibility() for migrations
• Provide a default minimal Model factory for safe pipeline creation and tests
• When adding new Element/Container types, add annotations and compatibility handlers to avoid breaking old models

Example use cases

• Create a new pipeline template programmatically using defaultModel() and then extend stages/containers
• Write a migration that transforms deprecated fields and calls transformCompatibility() for historic models
• Implement a cleanup tool that removes Elements by classType using removeElements()
• Extend CI to support a new container dispatch type and update JsonSubTypes and serialization logic
• Add matrix support to a Job by populating MatrixControlOption and expanding groupContainers at runtime