Plugin Development

About 652 wordsAbout 2 min

Plugin Development explains how to build and publish a Cloud Native Build plugin from scratch.

When to use: when a pipeline step needs custom behavior that you want to reuse across events or repositories - for example packaging your internal release process or a code-check tool into a plugin image that .cnb.yml can reference directly, instead of repeating a script in every step.

In Cloud Native Build, a plugin is essentially a Docker image. Below is how to develop an image plugin from scratch using Bash.

This example plugin prints hello world. Basic Docker knowledge is assumed.

Designing the Plugin

Parameter Design

Design the plugin parameters:

text: The text content to be printed to the console

These parameters are passed to the container as environment variables, converted to uppercase with a PLUGIN_ prefix.

Supported Parameter Types

Parameter types support string, number, boolean, one-dimensional array, and plain object.

Configuration example:

.cnb.yml
main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            text: hello world
            boolean: true
            number: 123
            array: [hello, world]
            map:
              key: value

These parameters are converted to the following environment variables inside the container:

PLUGIN_TEXT='hello world'
PLUGIN_BOOLEAN='true'
PLUGIN_NUMBER='123'
PLUGIN_ARRAY='hello,world'
PLUGIN_MAP='{"key":"value"}'

Arrays are comma-separated when passed to the container
Plain objects are converted to JSON strings

If the parameter structure is overly complex, consider storing them in a file and loading at runtime, simplifying the design, or splitting into multiple plugins.

Writing the Script

Write a Bash script to print the parameters:

#!/bin/sh
echo "$PLUGIN_TEXT"

Building the Plugin Image

The plugin is packaged as a Docker image for distribution. Create a Dockerfile to package the script and set it as the Entrypoint.

FROM alpine

ADD entrypoint.sh /bin/
RUN chmod +x /bin/entrypoint.sh

ENTRYPOINT /bin/entrypoint.sh

Build the image:

docker build -t cnbcool/hello-world .

Testing the Plugin

Test the plugin locally using docker run, passing parameters via environment variables:

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  cnbcool/hello-world

Testing Filesystem Access

The plugin can read the build process workspace directory. By default, the build directory is mapped to a plugin directory and set as the workspace:

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  cnbcool/hello-world

Exporting Variables

After a plugin finishes execution, you can output results using the ##[set-output key=value] format and then use the pipeline's exports to export them as environment variables for subsequent tasks.

Example: Exporting a GREETING Variable

Suppose the plugin needs to export hello world as the variable GREETING for use by a subsequent Job.

1. Modify the plugin script to output a custom variable:

entrypoint.sh
#!/bin/sh
echo "$PLUGIN_TEXT"

# Output a custom variable for exports
printf '##[set-output greeting=%s]\n' "$PLUGIN_TEXT"

Tips

##[set-output key=value] is parsed by CI into the Job's result object, which can then be exported as environment variables via exports.

2. Use exports in the pipeline to export the variable, and reference it in subsequent tasks:

.cnb.yml
main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            text: hello world
          exports:
            greeting: GREETING
        - name: use greeting
          script: echo $GREETING

After running, the second Job will output hello world.

exports supports exporting script execution results (code, stdout, stderr, info) and built-in task return values. See Environment Variables - Exporting Environment Variables for details.

Publishing the Plugin

A plugin is a Docker image — publishing a plugin means publishing the image.

You can publish to the built-in Artifact Registry of Cloud Native Build, or to Docker Hub for global availability.

Pushing the Image

docker push cnbcool/hello-world