Skip to main content

Plugin step

Plugins perform predefined tasks. They are essentially templated scripts that can be written in any programming language.

You can use plugins for anything. If it can be scripted, it can be a plugin. For example, you could use plugins that:

  • Scrape commit information from a Git repo.
  • Extract Jira issue numbers from Git commit messages.
  • Print an extended build history.
  • Create a file, write to it, and store it remotely.

Supported plugins​

You can build your own plugins or use one of the many preexisting plugins from the Drone Plugins Marketplace and GitHub Actions Marketplace.

Bitrise Workflow Steps aren't supported in the CD Plugin step at this time.

Creating custom plugins​

To create a plugin, you need to prepare a script, create a Docker image to run the script, and then build and publish the plugin image to a Docker registry.

  1. Write the script that you want the plugin to run. You can write plugins in any programming language. For example, the following Bash script, called clone.sh, clones a Git repo and prints the latest commit information.

    #!/bin/sh
    set -xe

    # If path setting is not set, then use current directory
    path=${PLUGIN_PATH:-.}
    mkdir -p ${path}
    cd ${path}

    # Clones the public git repo and checkout to a branch
    git clone ${PLUGIN_REPO_URL} .
    git checkout ${PLUGIN_BRANCH}

    # Prints the last commit
    git log -1 --stat
    Variables

    The above example script includes variable inputs: PLUGIN_PATH, PLUGIN_REPO_URL, and PLUGIN_BRANCH. Variables in plugin scripts become the plugin's Settings when you add the Plugin step to your Deploy stage.

  2. Create a Docker image to run your script by specifying the script as the ENTRYPOINT in a Dockerfile. For example, the following Dockerfile runs the clone.sh script:

    FROM alpine/git

    # Copies the clone script to the Docker image
    COPY clone.sh /usr/local/bin/

    # Makes the clone script executable
    RUN chmod +x /usr/local/bin/clone.sh

    ENTRYPOINT [ "/usr/local/bin/clone.sh" ]

  3. Using the method of your choice, build and publish the plugin image to a Docker registry. Take note of the Docker repo and image name, such as my-docker-repo/git-clone-plugin. You need it when you add the Plugin step to your Deploy stage.

    docker build -t my-docker-repo/git-clone-plugin .
    docker push my-docker-repo/git-clone-plugin

Test plugins locally​

You can test your plugin in a local environment by running it as a Docker container. For example, the following Docker command runs the clone.sh plugin locally by supplying the required inputs (PLUGIN_PATH, PLUGIN_REPO_URL, and PLUGIN_BRANCH) and specifying the plugin's Docker repo and image (my-docker-repo/git-clone-plugin).

docker run --rm \
 -e PLUGIN_PATH=codebase \
 -e PLUGIN_REPO_URL=https://github.com/<some-account>/<some-repo>.git \
 -e PLUGIN_BRANCH=main \
 my-docker-repo/git-clone-plugin

Distribute plugins​

Plugins are distributed as Docker images.

If your plugin image is private, others in your organization can use your plugin in their Harness CI pipelines by using a Docker connector configured for the private registry where your plugin image is stored.

If your plugin image is public, you can share it with anyone. You can submit a pull request to the drone-plugin-index repository if you'd like your plugin to be considered for the Drone Plugins Marketplace.

Plugin step settings​

The Plugin step has the following settings.

Container Registry and Image​

Container Registry is a Harness container registry connector that has access to Docker Hub. If you have created your own plugin, the connector must have access to the container registry where your plugin image is located.

The name of the plugin's Docker image. The image name should include the tag, or it defaults to the latest tag if unspecified. For more information about tags, go to Docker build tags.

You can use any Docker image from any Docker registry, including Docker images from private registries.

Privileged​

Select this option to run the container with escalated privileges. This is the equivalent of running a container with the Docker --privileged flag.

Settings​

Specify plugin-specific settings according to the plugin's documentation.

Output variables​

warning

Not all plugins write output variables.

Output variables are exposed values that can be used by other steps or stages in the pipeline. If the plugin writes output to the DRONE_OUTPUT.env file, you can use expressions to reference output variables in other steps and stages in the pipeline.

For example, to write to the DRONE_OUTPUT.env file, the plugin must use a command such as the following:

echo "VAR_NAME=somevalue" >> $DRONE_OUTPUT

To reference the resulting output variable in another step in the same stage, use either of the following expressions:

<+steps.STEP_ID.output.outputVariables.VAR_NAME>
<+execution.steps.STEP_ID.output.outputVariables.VAR_NAME>

To reference an output variable in a stage other than the one where the output variable originated, use either of the following expressions:

<+stages.STAGE_ID.spec.execution.steps.STEP_ID.output.outputVariables.VAR_NAME>
<+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.output.outputVariables.VAR_NAME>

For each expression:

  • Replace STEP_ID with the ID of the Plugin step.
  • Replace VAR_NAME with the relevant variable name.
  • In cross-stage references, replace STAGE_ID with the ID of the stage where the Plugin step exists.

If the step is within a step group, include the step group identifier in the expression, such as:

<+execution.steps.STEP_GROUP_ID.steps.STEP_ID.output.outputVariables.VAR_NAME>
<+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_GROUP_ID.steps.STEP_ID.output.outputVariables.VAR_NAME>

Image Pull Policy​

Select an option to set the pull policy for the image.

  • Always: The kubelet queries the container image registry to resolve the name to an image digest every time the kubelet launches a container. If the kubelet encounters an exact digest cached locally, it uses its cached image; otherwise, the kubelet downloads (pulls) the image with the resolved digest, and uses that image to launch the container.
  • If Not Present: The image is pulled only if it is not already present locally.
  • Never: The image is assumed to exist locally. No attempt is made to pull the image.

Set Container Resources​

Maximum resource limits for containers that clone the codebase at runtime. For more information, go to Resource units in Kubernetes.

Advanced settings​

In Advanced, you can use the following options: