Using the Octopus extension

We’ve created a public extension you can install into your Azure DevOps instance. This extension makes the following tasks available to your Build and Release processes:

• The Octopus Tools installer task.
• Pushing your package to Octopus.
• Push package build Information to Octopus
• Creating a release in Octopus.
• Deploying a release to an environment in Octopus.
• Promoting a release from one environment to the next.

You can also view the status of a project in an environment using the Dashboard Widget.

We’ve open-sourced the OctoTFS repository in GitHub if you’d like to contribute.

Installing the extension

You can install the extension from the marketplace and follow the instructions below.

If you’re using an earlier version of the formerly named Team Foundation Server, see the Extension Compatibility documentation for details on where to get a compatible extension.

After installing the extension, follow the below steps to get it running for your build.

Use your own version of Octo

You can bring your own version of the Octopus CLI and avoid the use of installer tasks or accessing the Internet by registering octo as a capability.

Add a connection to Octopus Deploy

Follow these instructions to create a new service connection and make sure you pick Octopus Deploy.

Enter a valid Octopus API Key in the API Key field and the Octopus Server url.

After you’ve saved the connection, it should be available from the Octopus Deploy Build Tasks.

Permissions required by the API key

The API key you choose needs to have sufficient permissions to perform all the tasks specified by your builds.

For the tasks themselves, these are relatively easy to determine (for example, creating a Release for Project A will require release creation permissions for that project).

For the Azure DevOps UI elements provided by the extension, the API key must also have the below permissions. If one or more are missing, you should still be able to use the extension, however the UI may encounter failures and require you to type values rather than select them from drop-downs. The dashboard widget will not work at all without its required permissions.

If there are scope restrictions (e.g. by Project or Environment) against the account, the UI should still work, but results will be similarly restricted.

• ProjectView (for project drop-downs)
• EnvironmentView (for environment drop-downs)
• TenantView (for tenant drop-downs)
• ProcessView (for channel drop-downs)
• DeploymentView (for the dashboard widget)
• TaskView (for the dashboard widget)
• BuildInformationPush (for pushing build information to Octopus)
  • BuildInformationAdminister (required if Overwrite Mode is set to Overwrite Existing)

Demands and the Octopus tools installer task

The Azure DevOps extension tasks require the Octopus CLI to be available on the path when executing on a build agent. Because of this we have created the “Octopus Tools installer” task that will download the Octopus CLI for you, you need to specify the version of the CLI you want to use. Alternative you can have the Octopus CLI available on the build agent.

Package your application and push to Octopus

To integrate with Octopus Deploy, an application must be packaged into either a NuGet, ZIP archive, or tarball, and pushed to Octopus Deploy (or any supported external feed by Octopus Server).

There are many ways to create such package formats in Azure DevOps, our recommended approach is to use the Archive Files task.

Add steps to your build or release process

Add a package application step

Add a step to your Build or Release process, our recommended approach is to use the Archive Files task.

Publish package artifact

If your Package Application step is part of your Build process and your Push Packages to Octopus step is part of your Release process, then you will need to add a Utility ➜ Publish Artifact step to make the package available to the Release process.

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: "$(Build.ArtifactStagingDirectory)"
    ArtifactName: "drop"
    publishLocation: "Container"

Add a push package(s) to Octopus step

Add a step to your build or release process, search for Push Packages(s) to Octopus task.

- task: OctopusPush@4
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Package: "$(Build.ArtifactStagingDirectory)/packages/*.zip"
    Replace: "true"

See the Extension Marketplace page for a description of the fields (or the Octopus CLI options for more details).

Add a push package build information to Octopus step

Add a step to your Build or Release process, search for Push Package Build Information to Octopus task.

- task: OctopusMetadata@4
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    PackageId: |
      OctoFX.Database
      OctoFX.RateService
    PackageVersion: "$(Build.BuildNumber)"
    Replace: "false"

- task: OctopusBuildInformation@6
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    PackageIds: |
      OctoFX.Database
      OctoFX.RateService
    PackageVersion: "$(Build.BuildNumber)"
    Replace: "false"

See the Extension Marketplace page for a description of the fields (or the Octopus CLI options for more details).

Add a create Octopus release step

Add a step to your Build or Release process, search for Create Octopus Release task.

- task: OctopusCreateRelease@5
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    ProjectName: "OctoFX"

- task: OctopusCreateRelease@6
  name: create_release
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    ProjectName: "OctoFX"

See the Extension Marketplace page for a description of the fields (or the Octopus CLI options for more details).

Add a deploy Octopus release step

Add a step to your Build or Release process,search for Deploy Octopus Release task.

- task: OctopusDeployRelease@5
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Project: "OctoFX"
    ReleaseNumber: "latest"
    Environments: "Test"

- task: OctopusDeployRelease@6
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Project: "OctoFX"
    ReleaseNumber: "$(create_release.release_number)"
    Environment: "Test"

- task: OctopusDeployReleaseTenanted@6
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Project: "OctoFX"
    ReleaseNumber: "$(create_release.release_number)"
    Environment: "Test"
    DeployForTenants: |
      Customer A
      Customer B
    DeployForTenantTags: |
      VIP Customers

See the Extension Marketplace page for a description of the fields (or the Octopus CLI options for more details).

Add a Run Runbook step

Add a step to your build or release process, search for Octopus Run Runbook task.

- task: OctopusRunRunbook@6
  name: backup-database
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Project: "OctoFX"
    Runbook: "Backup Database"
    Environments: "Production"

See the Extension Marketplace page for a description of the fields.

Add a promote Octopus release step

Add a step to your build or release process, search for Promote Octopus Release task.

- task: OctopusPromote@4
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Project: "OctoFX"
    From: "Test"
    To: "Production"

See the Extension Marketplace page for a description of the fields (or the Octopus CLI options for more details).

Add an Await Task

Add a step to your Build or Release process, search for Octopus Await Task.

- task: OctopusAwaitTask@6
  name: wait
  continueOnError: true
  inputs:
    OctoConnectedServiceName: "Octopus Server"
    Space: "Default"
    Step: deploy-release

See the Extension Marketplace page for a description of the fields.

The Step property is the name given to the OctopusDeployRelease@6 or OctopusRunRunbook@6 step that created the tasks to be awaited.

Use the dashboard widget

On your Azure DevOps dashboard, click the + icon to add a new widget, then search for “Octopus Deploy”. Add the Octopus Deploy Status widget.

Hover over the widget and click the wrench icon to configure the widget.

Select an Octopus Deploy connection (see the Add a Connection section for details), a Project, and an Environment.

The widget should refresh to show the current status of the selected project in the selected environment.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, June 28, 2023