The Octopus CLI can be used to automate the creation of releases using the create-release command. This allows you to easily integrate Octopus with other continuous integration servers.
This command creates a release, and optionally deploy it to one or more environments:
Creates (and, optionally, deploys) a release.
Usage: octo create-release [<options>]
Where [<options>] is any of:
Release creation:
--project=VALUE Name or ID of the project.
--defaultPackageVersion, --packageVersion=VALUE
Default version number of all packages to use
for this release. Override per-package using --
package.
--gitCommit=VALUE [Optional] Git commit to use when creating the
release. Use in conjunction with the --gitRef
parameter to select any previous commit.
--ref, --gitRef=VALUE [Optional] Git reference to use when creating
the release.
--version, --releaseNumber=VALUE
[Optional] Release number to use for the new
release.
--channel=VALUE [Optional] Name or ID of the channel to use for
the new release. Omit this argument to
automatically select the best channel.
--package=VALUE [Optional] Version number to use for a package
in the release. Format: StepName:Version or
PackageID:Version or
StepName:PackageName:Version. StepName,
PackageID, and PackageName can be replaced with
an asterisk. An asterisk will be assumed for
StepName, PackageID, or PackageName if they are
omitted.
Can be specified multiple times.
--git-resource=VALUE [Optional] Git reference to use for a Git resource
in the release. Format: StepName:GitRef or
StepName:GitResourceName:GitRef. GitRef can be
replaced with an asterisk. An asterisk means
use the step-defined default branch.
Can be specified multiple times.
--packagesFolder=VALUE [Optional] A folder containing NuGet packages
from which we should get versions.
--releaseNotes=VALUE [Optional] Release Notes for the new release.
Styling with Markdown is supported.
--releaseNoteFile, --releaseNotesFile=VALUE
[Optional] Path to a file that contains Release
Notes for the new release. Supports Markdown
files.
--ignoreExisting [Optional, Flag] Don't create this release if
there is already one with the same version
number.
--ignoreChannelRules [Optional, Flag] Create the release ignoring any
version rules specified by the channel.
--packagePrerelease=VALUE
[Optional] Pre-release for latest version of all
packages to use for this release. This argument
supports regex patterns.
--whatIf [Optional, Flag] Perform a dry run but don't
actually create/deploy release.
Deployment:
--progress [Optional] Show progress of the deployment.
--forcePackageDownload [Optional] Whether to force downloading of
already installed packages (flag, default false).
--waitForDeployment [Optional] Whether to wait synchronously for
deployment to finish.
--deploymentTimeout=VALUE
[Optional] Specifies maximum time (time span
format) that the console session will wait for
the deployment to finish(default 00:10:00). This
will not stop the deployment. Requires --
waitForDeployment parameter set.
--cancelOnTimeout [Optional] Whether to cancel the deployment if
the deployment timeout is reached (flag, default
false).
--deploymentCheckSleepCycle=VALUE
[Optional] Specifies how much time (time span
format) should elapse between deployment status
checks (default 00:00:10).
--guidedFailure=VALUE [Optional] Whether to use guided failure mode.
(True or False. If not specified, will use
default setting from environment).
--specificMachines=VALUE
[Optional] A comma-separated list of machine
names to target in the deployed environment. If
not specified all machines in the environment
will be considered.
--excludeMachines=VALUE
[Optional] A comma-separated list of machine
names to exclude in the deployed environment. If
not specified all machines in the environment
will be considered.
--force [Optional] If a project is configured to skip
packages with already-installed versions,
override this setting to force re-deployment
(flag, default false).
--skip=VALUE [Optional] Skip a step by name.
--noRawLog [Optional] Don't print the raw log of failed
tasks.
--rawLogFile=VALUE [Optional] Redirect the raw log of failed tasks
to a file.
-v, --variable=VALUE [Optional] Specifies the value for a prompted
variable in the format Label:Value. For JSON
values, embedded quotation marks should be
escaped with a backslash.
--deployAt=VALUE [Optional] Time at which deployment should start
(scheduled deployment), specified as any valid
DateTimeOffset format, and assuming the time
zone is the current local time zone.
--noDeployAfter=VALUE [Optional] Time at which scheduled deployment
should expire, specified as any valid
DateTimeOffset format, and assuming the time
zone is the current local time zone.
--tenant=VALUE [Optional] Create a deployment for the tenant
with this name or ID; specify this argument
multiple times to add multiple tenants or use
`*` wildcard to deploy to all tenants who are
ready for this release (according to lifecycle).
--tenantTag=VALUE [Optional] Create a deployment for tenants
matching this tag; specify this argument
multiple times to build a query/filter with
multiple tags, just like you can in the user
interface.
--deployTo=VALUE [Optional] Name or ID of the environment to
automatically deploy to, e.g., 'Production' or
'Environments-1'; specify this argument multiple
times to deploy to multiple environments.
Common options:
--help [Optional] Print help for a command.
--helpOutputFormat=VALUE
[Optional] Output format for help, valid options
are Default or Json
--outputFormat=VALUE [Optional] Output format, valid options are
Default or Json
--server=VALUE [Optional] The base URL for your Octopus Server,
e.g., 'https://octopus.example.com/'. This URL
can also be set in the OCTOPUS_CLI_SERVER
environment variable.
--apiKey=VALUE [Optional] Your API key. Get this from the user
profile page. You must provide an apiKey or
username and password. If the guest account is
enabled, a key of API-GUEST can be used. This
key can also be set in the OCTOPUS_CLI_API_KEY
environment variable.
--user=VALUE [Optional] Username to use when authenticating
with the server. You must provide an apiKey or
username and password. This Username can also be
set in the OCTOPUS_CLI_USERNAME environment
variable.
--pass=VALUE [Optional] Password to use when authenticating
with the server. This Password can also be set
in the OCTOPUS_CLI_PASSWORD environment variable.
--configFile=VALUE [Optional] Text file of default values, with one
'key = value' per line.
--debug [Optional] Enable debug logging.
--ignoreSslErrors [Optional] Set this flag if your Octopus Server
uses HTTPS but the certificate is not trusted on
this machine. Any certificate errors will be
ignored. WARNING: this option may create a
security vulnerability.
--enableServiceMessages
[Optional] Enable TeamCity or Team Foundation
Build service messages when logging.
--timeout=VALUE [Optional] Timeout in seconds for network
operations. Default is 600.
--proxy=VALUE [Optional] The URL of the proxy to use, e.g.,
'https://proxy.example.com'.
--proxyUser=VALUE [Optional] The username for the proxy.
--proxyPass=VALUE [Optional] The password for the proxy. If both
the username and password are omitted and
proxyAddress is specified, the default
credentials are used.
--space=VALUE [Optional] The name or ID of a space within
which this command will be executed. The default
space will be used if it is omitted.
--logLevel=VALUE [Optional] The log level. Valid options are
verbose, debug, information, warning, error and
fatal. Defaults to 'debug'.
Basic Examples
This creates a new release of the HelloWorld project using the latest available NuGet packages for each step in the project. The version number of the release will be the highest version according to the Release Versioning project setting:
octo create-release --project HelloWorld --server https://your-octopus-url --apiKey API-YOUR-KEY
This creates a release with a specified release number, overriding the Release Versioning project setting:
octo create-release --project HelloWorld --version 1.0.3 --server https://your-octopus-url --apiKey API-YOUR-KEY
Version controlled projects
For projects that use the Config as Code feature (they are version controlled), you can create a release pointing at a git reference, e.g. a branch name or tag. This example creates a release using the branch name of main:
octo create-release --project HelloWorld --version 1.0.3 --server https://your-octopus-url --apiKey API-YOUR-KEY --gitRef main
If the provided project is not a version controlled one, passing --gitRef (or --gitCommit) will result in an error as these parameters are only valid for projects that are version controlled.
Specifying the Package Version
For each step that has a package, the version is determined in the following order:
- The step name matches a
--packageparameter or a file filename found by--packagesFolder. - The package id matches a
--packageparameter or a file found by--packagesFolder. - The value from the
--defaultpackageversionor--packageversionparameter.
If there are duplicate names/ids resulting from the --package and --packagesFolder parameters, the last one specified is used.
Option —packageVersion
This creates a release (1.0.3) with a specified NuGet package version (1.0.1):
octo create-release --project HelloWorld --version 1.0.3 --packageVersion 1.0.1 --server https://your-octopus-url --apiKey API-YOUR-KEY
Option —package
This creates a release for a project with multiple packages, each with a different version. You can specify a step name and version pair with this option, allowing you to use different versions of the same package for different steps:
octo create-release --project HelloWorld --version 1.0.3 --package StepA:1.0.1 --package StepB:1.0.2 --server https://your-octopus-url --apiKey API-YOUR-KEY
If you want to use a specific version of a package for StepA, and the latest version of the package available for StepB, you can simply omit the parameter for the second step/package:
octo create-release --project HelloWorld --version 1.0.3 --package StepA:1.0.1 --server https://your-octopus-url --apiKey API-YOUR-KEY
The example above uses 1.0.1 for StepA, and the latest version available at the moment for StepB.
For steps which have multiple packages (e.g. Run a Script steps can reference multiple packages), the format StepName:PackageName:Version can also be used:
octo create-release --project HelloWorld --version 1.0.3 --package StepA:Acme.Web:1.0.0 --package StepA:Acme.Data:2.0.0 --server https://your-octopus-url --apiKey API-YOUR-KEY
In the example above, StepA uses 1.0.0 for Acme.Web and 2.0.0 for Acme.Data.
Option —packagesFolder
This creates a release for a project with multiple packages, by taking the version for each package from a folder containing the packages (this approach works well if your build server has just built the packages):
octo create-release --project HelloWorld --version 1.0.3 --packagesFolder packages --server https://your-octopus-url --apiKey API-YOUR-KEY
Deploying a release after creating it
To create a release and deploy it to an environment named Production:
octo create-release --project HelloWorld --deployto Production --server https://your-octopus-url --apiKey API-YOUR-KEY --progress
A note on lifecycle phases with automated deployment:
If the --deployTo parameter is specified and the lifecycle of the project you are deploying to is set to Deploy automatically when a release is created, it’s possible multiple deployments to the same environment will be triggered.
Release notes supported syntax
We use Showdown to render release notes on the dashboard. Showdown supports the common markdown syntax as well as a rich set of extras such as tables and task lists. For the full list see https://github.com/showdownjs/showdown/wiki/Showdown’s-Markdown-syntax.
Learn more
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Thursday, September 12, 2024