Octopus Step Packages: CLI

npm i --save-dev @octopusdeploy/step-package-cli

The Step Package CLI provides a set of tools to build, pack and publish step packages in a consistent manner, so that once built they are in a format that is guaranteed to work with Octopus Server.

Build

The build command:

• Loads package id and version information from the package.json file located via the packageDirectory parameter
• Locates convention-based step package contents by scanning for a metadata.json file located via the sourceDirectory parameter and looking for contents relative to it
• Will build the required node components (executor.js, validator.js) within the step package in CommonJS format
• Will build the required browser components (ui.js) within the step package in ESM format
• Will generate the required JsonSchema (inputs.json) from the default exported type in inputs.ts
• Will package the built contents into a zip file located in the outputDirectory

Publish

The publish command:

• Unzips one or more built step packages to be published via the packagePath parameter. A glob pattern can be used to process multiple packages.
• Loads the metadata from the package to construct a package manifest
• Uploads the manifest and package contents to the feed designated by the feedUrl parameter, using the apiKey parameter for authentication to the feed.
• If a package already exists in the feed a 409 Conflict error will be returned, this can be ignored using the ignoreExistingPackageErrors flag.

Execution Environment

Why CommonJS for node and ESM for the browser? Because ESM in node is currently painful.

Conventions

Step Packages are expected to follow these conventions:

• There is a metadata.json file that adheres to either the Step Metadata Schema or the Target Metadata Schema
• The executor is the default export of executor.ts
• The validator is the default export of validator.ts
• The UI is the default export of ui.ts
• The input type schema root is the default export of input.ts
• A logo is available as logo.svg
• All the above files are located alongside metadata.json in a single directory.

Multiple steps and deployment targets may exist in a Step Package, but they must exist in separate directories within it. See the Step Package Template Repository for a sample repository structure.

Code within the step package can be broken down into an arbitrary number of ts files, but the expected root files listed above must exist at the step root directory, and they must contain the expected default exports.

If these conventions are not followed, the CLI build will fail.

Additional Configuration

If a step package needs to supply additional configuration to esbuild (for example, to specify some external packages to ignore), it can provide a step-package.json, and declare a subset of the options available on esbuild.BuildOptions. This configuration will be contributed to the build of all of the components within the step package.