Create Packages with the Octopus CLI

Last updated 2020-02-14T06:42:32.7161232+00:00

The Octopus CLI (octo) is a command line tool that interacts with the Octopus Deploy REST API and includes a pack command to create packages either as Zip or NuGet packages for deployment with Octopus.

Installation

We recommend installing The Octopus CLI as a global tool using .NET Core which makes octo available as a command via the .NET CLI.

If you have the .NET Core 2.1.300 SDK available you can install the Octopus CLI on a machine or build agent as a global tool with the following command:

dotnet tool install Octopus.DotNet.Cli --global

Check the output to make sure the installation works correctly. After the installation has completed, you can run the following to verify the version of the Octopus CLI that was installed (if you're using Windows, remember to open a new command prompt):

dotnet octo --version

For more installation details, options, and update instructions, see The Octopus CLI Global Tool.

For a full list of the pack command options see Octopus CLI - Pack or run the following command:

C:\> dotnet octo help pack

Usage

At a minimum octo pack requires an ID:

dotnet octo pack --id="OctoWeb"

The above command will generate a NuGet package in the current working directory with a timestamp based version number such as:

OctoWeb.2018.6.26.190140.nupkg.

If you want to provide your own version, you can pass the --version parameter in the call to octo:

dotnet octo pack --id="OctoWeb" --version="1.0.0"

OctoWeb.1.0.0.nupkg

You can also change the output directory with the --outFolder parameter, and the folder which will be packed with the --basePath parameter.

dotnet octo pack --id="OctoWeb" --version="1.0.0" --basePath="folder/to/pack" --outFolder="destination/folder/path"

Creating Zip Packages

By default, octo will create NuGet packages. You can specify Zip packages with the --format parameter:

dotnet octo pack --id="OctoWeb" --version="1.0.0.0" --format=zip

OctoWeb.1.0.0.zip

This will create a zip package that contains the same files as the output folder of your build.

Packaging a .NET Core application

To package a .NET core application, first publish the application, and then call octo pack on the output folder for example:

dotnet publish ./OctoWeb.csproj --output ./dist
dotnet octo pack ./dist --id="OctoWeb" --version="1.0.0"

Please refer to Microsoft's publish and packing documentation for more information.

Packaging a .NET Core Library

If you are using .NET Core for class libraries, we recommend using dotnet pack from Microsoft.

dotnet pack ./SomeLibrary.csproj --output ./dist
dotnet octo pack ./dist --id="SomeLibrary" --version="1.0.0"

Packaging a .NET Framework Web Application

There are usually some extra steps required to get the resulting application built and deployable. Full framework web applications are a good example of this, where simply building the application will not give you the desired output. We still recommend Octopack for these cases. However, you may be able to achieve this using msbuild parameters such as:

msbuild ./OctoWeb.csproj /p:DeployDefaultTarget=WebPublish /p:DeployOnBuild=true /p:WebPublishMethod=FileSystem /p:SkipInvalidConfigurations=true /p:publishUrl=dist
dotnet octo pack ./dist --id="OctoWeb" --version="1.0.0-alpha0001"

Packaging Your Application From a Folder

If you have a build process that places all build outputs into a final destination folder (such as gulp, grunt, or webpack), you can package it using the Octopus CLI as well. For example, if you've defined an npm script which runs your build and places all associated content into the dist folder:

npm run build
dotnet octo pack ./dist --id="OctoWeb" --version="1.0.0"

Known Issues with Other Compression Libraries

These are known issues to be aware of with other compression libraries:

Atlassian Bamboo users who are using Adam Myatt's Zip File Task and are extracting to a Linux machine may find that the contents don't get extracted into the correct folder structure but instead flattened with the path as the file name. This is the result of a known issue whereby the task does not confirm to the correct PKWARE ZIP §4.4.17.1 specifications and is using a back slash instead of forward slash as the file separator. We would recommend avoiding this task where possible.
Prior to the .NET framework 4.6.1, the System.IO.Compression library incorrectly preserved the windows-style back slash separator for file paths. This has since been fixed from .NET Framework 4.6.1 and the fix carried over into .NET Core.
The PKZIP specification requires that Zip files only need to store dates in the internal file headers with two bytes in the MS-DOS format (whereas tar file headers are stored in UNIX epoch format). This means that unless the compression library makes use of extra fields in the file headers, that a file compressed at some point in time on a machine in one timezone, may result in misleading dates when uncompressed in a different timezone.

Octopus Deploy Documentation