Tasks in the Octopus extension use the Octopus CLI to execute commands with an instance of Octopus. As a result, the Octopus CLI is required to be installed and available on an agent before subsequent tasks run. There are two ways to fulfill this requirement:
- Use the tool installer task, Octopus CLI Installer as part of a build pipeline definition
- Install the Octopus CLI into a self-hosted agent
Using the tool installer task Octopus CLI Installer in a build pipeline definition is suitable for installing the Octopus CLI just in time for a build. This is required for builds executed on Microsoft-hosted agents, which do not offer the ability to pre-load custom software. Alternatively, the Octopus CLI may be installed on a self-hosted agent and expressed as a capability. Once configured, a pipeline may express demands of agents to ensure that the Octopus CLI is available when executing builds.
Using the Octopus CLI Installer
The Octopus CLI Installer task downloads and installs the Octopus CLI, making it available to other tasks in a build pipeline definition. It can be added to a definition through the Classic editor of Azure Pipelines or through the YAML pipeline editor.
Currently, the Octopus extension ships two versions of the Octopus CLI Installer task; version 4 is provided for backward compatibility with older pipeline definitions while version 5 is recommended because it offers additional features.
Octopus CLI Installer v4
In the Classic editor, version 4 of the Octopus CLI Installer task has a required field, Octopus CLI Version
that is used to specify the version of the Octopus CLI to be installed:
The accepted values for this field are:
embedded
: use the built-in version of the Octopus CLIlatest
: downloads and installs the latest version of the Octopus CLI- A specific version number of the Octopus CLI to use e.g.
7.4.3556
Wildcards not supported Please note: Wildcard values are NOT supported when providing a specific version of the Octopus CLI to use.
The Octopus CLI Installer task may be used in a YAML-based build pipeline. Using the YAML pipeline editor, the following snippet will download and install the latest version of the Octopus CLI:
- task: OctoInstaller@4
displayName: "Octopus CLI Installer"
inputs:
version: "latest"
Octopus CLI Installer v5
In the Classic editor, version 5 of the Octopus CLI Installer task has a required field, Octopus CLI Version
that is used to specify the version of the Octopus CLI to be installed:
This field accepts a limited set of values, specified as MAJOR.MINOR.PATCH
with wildcard support that adheres to Semantic Versioning rules. For example:
8.*
: install latest minor version for v8 of the Octopus CLI7.3.*
: install the latest patch version for v7.3 of the Octopus CLI9.0.0
: install the exact version 9.0 of the Octopus CLI*
: install the latest version of the Octopus CLI
Range operators not supported
Please note: Range and range operators e.g. ~1.2.3
are not supported.
The Octopus CLI Installer task may be used in a YAML-based build pipeline. Using the YAML pipeline editor, the following snippet will download and install the latest version of the Octopus CLI:
- task: OctoInstaller@5
displayName: "Octopus CLI Installer"
inputs:
version: "*"
Octopus CLI Installer v6
Version 6+ of each of the steps no longer require installing the CLI
Version 6 of the Octo CLI installer will only install the new Octopus CLI.
Using the Octopus CLI with Self-Hosted Agents
Self-hosted agents provide the ability to install tools that are required for builds and deployments. They can also improve build performance since their associated configuration is persisted between runs.
Self-hosted agents are available for Linux, macOS, or Windows. They may also be used in a Docker container. For more information about installing a self-hosted agent, see:
- macOS agent
- Linux agent (x64, ARM, ARM64, RHEL6)
- Windows agent (x64, x86)
- Docker agent
A self-hosted agent must be configured to include the Octopus CLI before using it in a pipeline. Binaries and/or packages for the Octopus CLI can be downloaded from the Octopus CLI downloads page.
Breaking Change in Version 5
Tasks in version 5 of the Octopus extension now assert demands for agent capabilities. These tasks now require that self-hosted agents expose the user-defined capability octo
along with the version of the Octopus CLI installed on the agent (i.e. 8.0.1
).
These task demands were introduced and mandated in version 5 to ensure the availability of the Octopus CLI.
If this user-defined capability described above is not defined for self-hosted agents then jobs will fail with the following error:
No agent found in pool [POOL-NAME] which satisfies demands: octo
Please note that tasks in version 4 (and below) of the Octopus extension do not assert demands for agent capabilities. Therefore, it is not required to specify agent capabilities for these tasks.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023