Skip to main content

Adding Plugins to Cycle

Plugins are installed directly into Cycle's installation directory on the local machine. Plugging a step plugin into Cycle requires special setup. A plugin author must write a settings file and install the plugin's artifacts into the Cycle directory.

Setting the plugin version​

A step plugin should set version numbers to better keep track of features and updates. Semantic Versioning is recommended. For plugins developed using the Java Plugin SDK, the plugin's version number should be set in the pom.xml file as well as in the settings.yml file. As a recommended practice, increase the version number for every new plugin release.

Writing the settings file​

The step plugin requires a settings file named settings.yml that provides information for running the step plugin. In Java plugin projects, this file is conventionally located in the Maven src/main/resources directory, along with the steps.yml step spec file. The file format looks like this:

# The plugin's name.
name: My Step Plugin

# The plugin's version.
version: 0.1.0

# The plugin's commands.
commands:

  # The command that Cycle will call to start the step plugin as a local service.
  start:

    # The plugin's executable type.
    # Options: [exe|jar|script]
    type: jar

    # The name of the executable artifact in the plugin directory.
    file: my-step-plugin.jar

    # Cycle provides a port number to the step plugin when starting its service.
    # The step plugin must provide the mechanism for receiving the port number.
    # It can use either a command line argument flag or an environment variable.
    # The plugin author should specify exactly one, but not both.
    # If the plugin is built using the Java Plugin SDK, use `SERVER_PORT`.
    # Java's Spring Boot web framework uses the `SERVER_PORT` environment variable.
    portEnvironmentVariableName: SERVER_PORT
    # portFlagName: --port

# Dependencies on other plugins by name.
# If there are no dependencies, then this section may be removed.
dependencies:
  - Another Plugin

All the fields are required except the dependencies field. If the plugin must call steps provided by another plugin, then add the names of those dependency plugins to the dependencies field.

Installing the plugin​

All step plugins should be installed into a subdirectory under the Cycle installation folder: .../CycleLabs/Cycle/plugins/<step-plugin>, where <step-plugin> is a directory name for the step plugin.

Each step plugin directory must contain the following:

  • a step spec file named steps.yml
  • a settings file named settings.yml
  • the executable artifacts (like a JAR file, an EXE file, or a directory of scripts)
  • any other files the executables need

For plugins written with the Java Plugin SDK, the executable artifact should be a JAR file. It must be a "built" artifact, not source code or project files. The JAR file does not need to include source code files. It should be built to target Java 21, which is the version of Java that Cycle runs.

Note that these files must be in the top-level of the step plugin directory. If you are developing a plugin project in Java, then the step spec and settings file are likely in the project's src/main/resources folder. You will need to copy and paste them into the step plugin directory along with the built JAR file.

Restarting Cycle after installation​

After installing a new step plugin, restart the editor (either the Cycle Desktop IDE or the Cycle Testing VS Code extension) for Cycle to start using the new steps. After restarting, make sure the editor does not issue any step plugin error notifications. Resolve any errors that appear before attempting to write and run Cycle tests.

Updating or uninstalling Cycle​

When Cycle is updated to a new version (such as updating from 2.26 to 2.27), any step plugins that you have added to Cycle will be saved. They will not be deleted or removed. You can continue using them in the updated Cycle version.

When Cycle is uninstalled from the local machine, all Cycle files in the installation directory including any step plugins that you have added will be deleted. If you reinstall Cycle fresh, you will need to reinstall the desired step plugins with it.