Script Jobs vs Plugin Jobs
About 1102 wordsAbout 4 min
Overview
In the CNB pipeline, a Job is the smallest execution unit, primarily categorized into three types: Script Jobs, Plugin Jobs, and Built-in Jobs. Both the first two types support specifying the image parameter to define the runtime environment, which can often be confusing for newcomers. This document provides a detailed comparison of the characteristics and use cases of these two job types to help you make informed decisions.
Similarities
- Both can specify
imageto define the execution environment - Both execute in isolated container environments, avoiding pollution of the host or other jobs
- Both can use CNB built-in system environment variables (e.g.,
CNB_REPO_SLUG,CNB_COMMIT)
Differences
| Feature | Script Job | Plugin Job |
|---|---|---|
| Execution | Uses image as environment, executes Shell commands specified by script or commands | Runs ENTRYPOINT built into image, acts as a functional module |
| Default Environment | Executes in pipeline container environment if image is not specified | Must specify image |
| Parameter Passing | Declares environment variables via env or imports | Specifies parameters via settings, injected as PLUGIN_ + uppercase parameter name |
| Environment Variable Restrictions | No restrictions | Only CNB built-in variables available; env/imports not passed |
| Flexibility | High, can execute arbitrary Shell commands | Preset by plugin developer, configured via settings |
| Reusability | Strongly tied to business logic | Cohesive functionality, easy to reuse |
| Version Control | Script follows code repository version control | Defaults to latest if version not specified; plugin updates may cause configuration failures |
Execution Method
Script Job: Uses image as environment, you have full control to execute arbitrary Shell commands.
- name: install dependencies
image: node:20 # Specify execution environment; if not specified, runs in pipeline container environment
script: npm install # Execute Shell commands
env:
NODE_ENV: production # Declare environment variables via envPlugin Job: Runs preset ENTRYPOINT from plugin image, configures plugin behavior via settings parameters.
- name: npm publish
image: plugins/npm # Run plugin image, execute built-in ENTRYPOINT
settings:
username: $NPM_USER # Specify parameters via settings
password: $NPM_PASS
registry: https://registry.npmjs.org/The above plugin job injects environment variables:
PLUGIN_USERNAMEPLUGIN_PASSWORDPLUGIN_REGISTRY
Parameter Passing
Script Job environment variable passing:
- Declare environment variables via
env - Import environment variables from files via
imports - Priority:
Job env>Stage env>Pipeline env
Plugin Job parameter passing:
- Specify parameters via
settings(parameters injected withPLUGIN_prefix) - Load parameters from files via
settingsFrom - Pass command-line arguments via
args - Note: Custom environment variables declared via
envandimportsare not passed to plugins
Environment Variable Restrictions
Script Job:
- ✅ Can use custom environment variables declared by
env - ✅ Can use environment variables imported via
imports - ✅ Can use CNB built-in system environment variables
Plugin Job:
- ❌ Cannot use custom environment variables declared by
env(not passed) - ❌ Cannot use environment variables imported via
imports(not passed) - ✅ Can use CNB built-in system environment variables
- ✅ Can reference environment variables via variable substitution in
settingsandargs
# Correct: Reference environment variables in settings
- name: correct plugin usage
image: plugins/npm
settings:
username: $NPM_USER # ✅ Correct: Reference environment variables for variable substitution
password: $NPM_PASS
# Incorrect: Attempt to pass parameters to plugin via env
- name: wrong plugin usage
image: plugins/npm
env:
PLUGIN_USERNAME: $NPM_USER # ❌ Incorrect: This will not be passed to the plugin
PLUGIN_PASSWORD: $NPM_PASSBest Practices
1. Version Control
Plugin Job: Always specify image version, avoid using latest tag to prevent plugin updates from causing pipeline failures.
# Recommended: Specify version
- name: npm publish
image: plugins/npm:1.2.3
settings:
username: $NPM_USER
# Not recommended: Using latest (plugin updates may cause configuration failures)
- name: npm publish
image: plugins/npm # Defaults to latest
settings:
username: $NPM_USERScript Job: Script logic follows code repository version control, no additional attention needed.
2. Security Considerations
Plugin Job:
- Use official or trusted plugin images
- Regularly check plugin image security updates
- Store sensitive information in secret vault
Script Job:
- Avoid hardcoding sensitive information in scripts
- Use environment variables to pass secrets
- Use secret vault to manage configuration
3. Reusability Considerations
Plugin Job is suitable for encapsulating reusable functionality:
- Message notifications (WeChat Work, Feishu, DingTalk, etc.)
- Generic CI/CD operations (publish, deploy, etc.)
- Code quality checks (lint, scanning, etc.)
These features can be published to the CNB plugin marketplace for other developers to use.
Script Job is suitable for business-related logic:
- Code building and testing
- Custom data processing
- Specific business workflows
These logic are often strongly related to the project and have lower reusability.
4. Selection Recommendations
| Scenario | Recommended Type | Reason |
|---|---|---|
| Generic CI/CD operations (publish, deploy) | Plugin Job | Mature solutions available in plugin marketplace |
| Message notifications (WeChat, Feishu, DingTalk) | Plugin Job | Cohesive functionality, simple configuration |
| Code building and testing | Script Job | Flexible control, adapts to various tools |
| Custom business logic | Script Job | Need complete control over execution flow |
| Calling external APIs | Script Job | Flexible handling of various API formats |
| Generic functionality for reuse | Plugin Job | Can share to plugin marketplace |
FAQ
Q1: Why can't plugin jobs pass environment variables via env?
A: Plugin jobs are designed with functional modularity in mind, using settings to clearly define the parameters a plugin accepts rather than passing all environment variables. Benefits include:
- Clear plugin interface, avoiding parameter confusion
- Plugins can explicitly declare required parameters
- Improved security and maintainability
Q2: Where do script jobs execute when image is not specified?
A: When a script job does not specify image, it executes in the pipeline container environment. The pipeline container environment is specified by Pipeline.docker.image or Stage.image.
main:
push:
- docker:
image: node:20 # Pipeline container environment
stages:
- name: without image
# image not specified, executes in node:20 environment
script: node -v
- name: with image
# Specify image, executes in python:3.9 environment
image: python:3.9
script: python --versionQ3: How to use environment variables in plugin jobs?
A: Use variable substitution in settings or args.
- name: plugin with env
image: plugins/npm
settings:
username: $NPM_USER # Use variable substitution
password: $NPM_PASSQ4: Can plugin jobs execute custom scripts?
A: Plugin job execution logic is preset by the plugin image and does not support executing custom scripts. If you need to execute custom scripts, use script jobs.
Q5: How to decide whether to use script jobs or plugin jobs?
A: Ask yourself the following questions:
- Is there an existing plugin that meets the requirements? → Use plugin job
- Do you need flexible custom command execution? → Use script job
- Can the functionality be reused and shared? → Consider plugin job
- Is the functionality strongly related to business logic? → Use script job
Summary
Script jobs and plugin jobs each have their advantages:
- Script Job: High flexibility, suitable for custom business logic
- Plugin Job: Cohesive functionality, easy to reuse and share
Choosing the appropriate job type can simplify configuration, improve reusability, while maintaining necessary flexibility.