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.
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
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:
If you want to provide your own version, you can pass the
--version parameter in the call to
dotnet octo pack --id="OctoWeb" --version="1.0.0"
You can also change the output directory with the
--outFolder parameter, and the folder which will be packed with the
dotnet octo pack --id="OctoWeb" --version="1.0.0" --basePath="folder/to/pack" --outFolder="destination/folder/path"
Creating Zip Packages
octo will create NuGet packages. You can specify Zip packages with the
dotnet octo pack --id="OctoWeb" --version="22.214.171.124" --format=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
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 §126.96.36.199 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.