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 image to 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 env

Plugin 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_USERNAME
• PLUGIN_PASSWORD
• PLUGIN_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 with PLUGIN_ prefix)
• Load parameters from files via settingsFrom
• Pass command-line arguments via args
• Note: Custom environment variables declared via env and imports are 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 settings and args

# 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_PASS

Best 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_USER

Script 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 --version

Q3: 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_PASS

Q4: 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:

1. Is there an existing plugin that meets the requirements? → Use plugin job
2. Do you need flexible custom command execution? → Use script job
3. Can the functionality be reused and shared? → Consider plugin job
4. 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.