Octopus and NuGet Package naming conventions differ ~ Release deploys wrong package

The following has caused me quite a headache.

Nuget requires packages to start with the Version ID, followed by any identifiers, such as:


Meanwhile, Octopus requires packages to have their Version after any identifiers, such as:


This naturally causes problems when trying to use both in one pipeline. In my case, I was packaging a package with NuGet and then trying to push it with Octopus, which caused Octopus to start using the wrong packages as soon as multiple different packages were in the system.

In my case, I had packages with the following NuGet-conform identifiers:


And while the develop builds would correctly deploy the develop packages, the alpha builds would incorrectly deploy the develop packages as well, even though a newer alpha package was available in the package feed.

I eventually managed to fix this by providing the following parameter to our TeamCity configuration, with %build.number% being the variable that translates to either 0.0.0-alpha.379 or 0.0.0-develop.34 in this case:


I find this a bit redundant since I already specified %build.number% in the Release number: field in the TeamCity build step configuration, but then I guess Octopus has no way of knowing that this is the package name we intend for it to use. The curious consequence of this was that I had releases called “0.0.0-alpha.379” that deployed package “0.0.0-develop.34”.

In fact, the first thing I checked upon running into this issue was if the TeamCity “Octopus: Create Release” build step had a field for specifying the package ID, which would have been the first thing I would have tried. Since it didn’t, it took me some time to come to the above mentioned solution. I don’t know if this is the right place to request this, but maybe it would be a good idea to include such a field in the TeamCity Octopus plugin? After all, one of the things that has always puzzled me thus far is "How does Octopus know which package I want to deploy if there is no field to specify it?


Hi Kira, thanks for reaching out.

Octopus and Nuget both rely on Semver versions for packages, so any package use Nuget will also work with Octopus.

Taking the example with the versions you supplied of 0.0.0-alpha.379 and 0.0.0-develop.34, the reason why Octopus would default to using the develop version is because this version is the latest. For example, if there are two packages uploaded to Octopus of helloworld.0.0.0-alpha.379.zip and helloworld.0.0.0-develop.34.zip, Octopus sees these two packages as sharing single package id (helloworld) and two versions (0.0.0-alpha.379 and 0.0.0-develop.34). Because of how Semver compares versions, 0.0.0-develop.34 is considered later than 0.0.0-alpha.379, and Octopus defaults to selecting the latest version.

You can use the tool at http://semvercompare.azurewebsites.net/?version=0.0.0-alpha.379&version=0.0.0-develop.34 to see how Semver versions compare against each other.

I’m not sure what you are referring to when you talk about “develop builds” or “alpha builds”. However by default Octopus makes no distinction between packages based on the Semver prerelease versions, which is to say by default the alpha and develop part of the versions are not significant beyond being used for a direct version comparison.

If you are trying to create builds in Octopus that only work with a specific prerelease version, you will need to use channels. Using a channel rule you can define a regular expression rule that must match a prerelease version. You can find more information on channels at https://octopus.com/docs/deployment-process/channels.

For example the screenshot below shows a channel rule that only matches packages with the alpha prerelease version. When the step that this channel rule is associated with is deployed, only packages with the alpha prerelease version will be considered.

Note that an Octopus release number does not have any effect on package version numbers. This only defines the version of the Octopus release, but does not define the packages that went into the release. While it is common for the Octopus release number to match the version of a package that was deployed as part of it, this relationship is not enforced by default.

To specify the version of a package that is included in an Octopus release, you need to supply the --package option in Additional command line arguments field. You can find more information on these switched at .https://octopus.com/docs/api-and-integration/octo.exe-command-line/create-release. The screesnshot below shows where you enter additional arguments like --package.

So, in summary:

  • By default semver prerelease versions are only significant to Octopus for direct comparisons. Prerelease versions like alpha and developer are not otherwise use for grouping or isolating packages.
  • Octopus can be configured to only consider specific prerelease versions through channels.
  • To force an Octopus deployment to use a specific package version, you need to pass the --package option as part of the OctopusDeploy: Create release step.

Matt C

Hi Matt,

thank you for the explanation. The Link to http://semver.org/ was particularly enlightening, and after reading through that it now all makes sense.

I’ve settled on using the --package=Project-Name:%build.number% option now since what we’re doing is pretty much deploying a TeamCity build that builds and pushes a version, and then want to have that specific Version and not any other Version deployed on our test server. Since I consider this to be a common scenario, I really think the Octopus TeamCity plugin could use an optional field to specify a version to deploy.

I still remember the first time I used the Octopus TeamCity plugin. One of the first questions I had upon seeing the interface for creating a release was “Okay, and where do I specify which version I want to have deployed?”. Knowing what I do now, I believe an optional field for “Version to be deployed” with the sub-title “Leave empty to auto-detect and deploy latest version” would make it so much more intuitive to use.

Either way, thank you very much for clearing this up,

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.