pipeline-plugin-development

Pipeline Plugin Development

Applicable Scenarios

• Add a pipeline plugin
• Modify task.json configuration and field definitions
• Design plugin inputs, outputs, error codes, and sensitive fields
• Choose a plugin implementation approach such as Java, Python, NodeJS, Golang, etc.
• Debug, test, publish, or troubleshoot plugin behavior

Inapplicable Scenarios

• Modify how the Worker executes plugins
• Modify how the Agent starts the Worker
• Modify how Dispatch schedules build machines
• Modify the pipeline model, YAML conversion, or template system

Quick Guidance

1. This skill focuses on "how the plugin itself is defined and delivered", not "how the plugin is executed".
2. First confirm that you are developing an Atom, not modifying the executor chain.
3. When developing a plugin, prioritize three types of information:
   • Plugin basics and directory:reference/1-plugin-foundation.md
   • task.json, inputs/outputs and error codes:reference/2-task-json-io.md
   • Debugging, publishing, and best practices:reference/3-debug-publish-practice.md
4. task.json is the plugin contract; field design, runtime configuration, and sensitive information marking should all be clearly defined here first.
5. Inputs and outputs should aim for a "stable contract"; do not expose temporary implementation details to users.
6. The runtime and target platform should be clarified as early as possible to avoid adding compatibility after release.
7. If the problem occurs during the stage when the plugin is downloaded, executed, logged, or its artifacts are archived, you usually need to switch to worker-module-architecture。

High-Signal Rules

• The core objects of plugin development are task.json and the plugin execution entry point
• Input fields, output variables, and error codes are contracts visible to users
• Multilingual support is only an implementation means; contract stability is more important than language choice
• After a plugin is published, it will be reused by many pipelines, so compatibility and backward compatibility should be prioritized

Key Pitfalls

• Misjudging an executor problem as a plugin problem
• task.json Cramming too many frontend/runtime details into it, making it hard to maintain
• Ignoring sensitive fields, default values, and validation rules
• Writing the implementation first and adding the contract later, ultimately causing unstable inputs and outputs

Further Reading

• Plugin basics and directory:reference/1-plugin-foundation.md
• task.json, inputs/outputs and error codes:reference/2-task-json-io.md
• Debugging, publishing, and best practices:reference/3-debug-publish-practice.md
• If the problem occurs during the execution stage: see also worker-module-architecture
• If the problem occurs in the pipeline model: see also pipeline-model-architecture