Installing the Octopus CLI as a capability

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:

1. Use the tool installer task, Octopus CLI Installer as part of a build pipeline definition
2. 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 CLI
• latest: 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

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 CLI
• 7.3.*: install the latest patch version for v7.3 of the Octopus CLI
• 9.0.0: install the exact version 9.0 of the Octopus CLI
• *: install the latest version of the Octopus CLI

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 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.

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.

Send feedback

Page updated on Sunday, January 1, 2023