A plugin is a Docker container that performs a predefined task. Plugins are essentially templated scripts that can be written in any programming language. The Drone community maintains an extensive library of plugins for specific CI workflows. You can customize and extend your build processes using existing plugins or write your own.
This topic describes how to set up and run plugins in your CI Pipelines.
Before You Begin
To install and run a plugin, you need the following:
- A familiarity with basic Harness CI concepts:
- A build infrastructure and Delegate to run builds:
- A CI Pipeline with a Build Stage to run the plugin:
- You should create text secrets for any sensitive information required by the plugin, such as a password or Personal Access Token. You'll need to reference the IDs for any secrets when you set up the Plugin Step.
The following steps describe the high-level workflow:
- Go to the Pipeline and open the Build step where you want to run the plugin.
- In the Execution tab, click Add step and select Plugin.
- Enter the following:
- Name: A unique, descriptive name.
- Container Registry: A Connector to the image registry (such as Docker Hub) of the plugin image.
- Image: The full image name, such as
dockerhubusername/my-plugin:2.3.1. The Step uses the latest image if you don't specify a tag.
- Under Optional Configuration > Settings, add any other settings that are required as specified in the docs for the specific plugin.
- Click Apply Changes to apply your Stage settings, then Save to save the updated Pipeline
- Run the updated Pipeline and check the log output to verify that the Plugin Step works as intended.
Simple Example: Download a File
This example describes how to run the Drone Downloads plugin, which downloads an archive to your build infrastructure. You can use the following workflow to implement any plugin.
- Go to the Drone Plugins Hub and read the description for the specific plugin. The description should indicate the plugin image and the required settings.
The Download plugin doc shows the image to use (
plugins/download) and the settings that the plugin supports:
password, and so on.
- Go to the Build Stage in a CI Pipeline. In the Execute tab, add a Plugin step.
- Configure the Step as follows.
Name: A unique, descriptive name.
Container Registry: A Connector to Docker Hub.
Image: The plugin image --in this case,
Under Optional Configuration, add the following settings:
source= The artifact to download.
destination= Save the downloaded artifact to this file.
username= A valid username for the Git provider.
password= The ID of the text secret that contains the Git provider password, using the convention described here. For example:
Click Apply Changes to apply your Stage settings, then Save to save the updated Pipeline
Run the updated Pipeline and check the log output to verify that the Plugin Step works as intended.
Drone Plugin YAML and CI Step YAML
You can use the examples in Drone plugin descriptions to configure a Plugin Step in the Pipeline YAML editor. The formats are slightly different, but close enough that translating Drone Plugin definitions to Harness CI is fairly simple. You can see additional examples in this blog post.
Text Secrets in Drone vs. Harness CI
The following snippets illustrate the different ways that Drone and Harness CI handle text secrets. See Add and Use Text Secrets.
Note that the CI definition includes a few additional fields and that some fields use different formats.
Example from Drone Download description
- name: download
Equivalent definition in Harness CI Pipeline
Define Nested and List Settings
You can specify nested and list settings in a Pipeline YAML definition, as shown here. It's easier to define complex settings in the YAML editor than the UI.
The settings appear in the UI like this: