Run a Drone Plugin in CI
A Drone 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 Drone Plugins in your CI pipelines. You can also use GitHub Action plugin steps and Bitrise plugin steps to run GitHub Actions and Bitrise Integrations 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.
Workflow Description
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 Marketplace 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:source
,destination
,username
,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,
plugins/download
- 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:<+secrets.getValue("mygithubpersonalaccesstoken")>
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.
Convert Drone Plugin YAML to Harness CI YAML
You can use YAML examples in the Drone Plugins Marketplace to configure a Plugin step in Harness CI. While the formats are slightly different, it is fairly simple to translate Drone Plugin definitions to Harness CI YAML.
Listed and nested settings
To list-formatted settings from Drone Plugin YAML to Harness CI YAML, merge them with comma separation.
- Drone Plugin YAML
- Harness CI YAML
Settings:
tags:
- latest
- '1.0.1'
- '1.0'
settings:
tags: latest,1.0.1,1.0
For nested settings, maintain key-value pair definitions, as shown in the following Harness CI YAML example:
settings:
mynestedsetting:
nextlevel:
varname: 100
mylistsetting:
- itemone
- itemtwo
It's often easier to define complex settings in the Pipeline Studio's YAML editor, rather than the Visual editor. The settings in the above example would be defined in the Visual editor as shown in the following screenshot.
Text Secrets
The following snippets illustrate the different ways that Drone and Harness CI handle text secrets.
Note that the CI definition includes a few additional fields and that some fields use different formats.
- Drone Plugin Marketplace definition
- Harness CI definition
steps:
- name: download
image: plugins/download
settings:
username:
from_secret: username
password:
from_secret: password
source: https://github.com/drone/drone-cli/releases/download/v0.8.5/drone_linux_amd64.tar.gz
- step:
type: Plugin
name: download-drone
identifier: downloaddrone
spec:
connectorRef: mygithubconnector
image: plugins/download
privileged: false
settings:
username: <+secrets.getValue("myusernamesecret")>
password: <+secrets.getValue("mypasswordsecret")>
source: https://github.com/drone/drone-cli/releases/download/v0.8.5/drone_linux_amd64.tar.gz
More examples
You can see additional examples in the GitHub Actions Support in Harness CI blog post.