The new structure of Team Foundation Build gives us a great opportunity to integrate better with your build and release processes from Visual Studio Team Services (VSTS) (formerly VSO) and on-premises Team Foundation Server (TFS) servers. We've created a public extension you can install into your VSTS instance or TFS 2017 server. This extension makes the following tasks available to your Build and Release processes:
- Octo Installer task
- Packaging your application
- Pushing your package 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.
On this page:
- Installing the Extension
- Use Your Own Version of Octo
- Add a Connection to Octopus Deploy
- Demands and the Octo Installer Task
- Package your Application and Push to Octopus
- Add Steps to your Build or Release Process
- Add a Promote Octopus Release Step
- Using the Dashboard Widget
- In This Section
We've open-sourced the OctoTFS repository in GitHub if you'd like to contribute.
Installing the Extension
If you're using Visual Studio Team Services (VSTS) or on-premises Team Foundation Server (TFS) 2017 (or newer) you can simply install the extension from the marketplace and follow the instructions below.
If you're using an earlier version of TFS, 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.
Manually installing the extension (not recommended)
If you want to make changes to the build task that might not be appropriate for everyone, you can download and manually install the build task yourself. See Manually install the Build Task (not recommended) for details.
Use Your Own Version of Octo
You can bring your own version of Octo and avoid the use of installer tasks or accessing the internet by registering Octo as a capability.
Add a Connection to Octopus Deploy
Hover over the Manage Project cog in the top right corner of the project screen in Visual Studio Team Services, and click the Services link.
Click New Service Endpoint and choose Octopus Deploy.
Specify a Connection Name and specify the Server Url to your Octopus Server (including the port if required).
Enter a valid Octopus API Key in the API Key field.
After you've saved the connection, it should be available from the Octopus Deploy Build Tasks.
if you plan to use the Octopus widgets and want them to function for users other than project collaborators, such as stakeholders, then those users must be explicitly allowed to use the service endpoint. This can be achieved by adding those users to the service endpoint
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 VSTS 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 dropdowns. 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 dropdowns)
- EnvironmentView (for environment dropdowns)
- TenantView (for tenant dropdowns)
- ProcessView (for channel dropdowns)
- DeploymentView (for the dashboard widget)
- TaskView (for the dashboard widget)
Demands and the Octo Installer Task
The VSTS extension tasks require Octo to be available on the path when executing on a build agent and must have the .net core 2.0.0 runtime or newer installed. This may not always be possible such as with the VSTS hosted agents. In order to make this work, all Octopus tasks will automatically attempt to download and use the latest version of Octo tools unless they're available on the build agent as specified above. If you would like to avoid any additional downloads or to use a specific Octo version then you can by adding the Octo Installer task to the start of your build definition. No attempt will be made to download Octo if the capability is detected on your build agent.
Version 2.x.x of the extension included a bundled version of the Octo tools and did not require the agent to be setup with Octo in the path and did not support running on Linux or Mac build agents.
Package your Application and Push to Octopus
To integrate with Octopus Deploy, an application must be packaged into either a NuGet or Zip package, and pushed to Octopus Deploy (or any NuGet repository).
We strongly recommend reading the Build Versions in Team Build guide for advice around build and package versions.
There are two options for packaging and pushing:
- Use the Package Application Steps added by this extension.
- Use OctoPack as part of your build process.
Using OctoPack to Create and Push a Package
Follow the OctoPack instructions to add OctoPack to your project and configure the msbuild arguments.
In the new Team Foundation build process, the arguments below should be in the MSBuild Arguments field for the Visual Studio Build or MSBuild step. Here is a list of the available variables that you can use from the Microsoft Build use variables.
/p:RunOctoPack=true /p:OctoPackPublishPackageToHttp=http://path.to.octopus/nuget/packages /p:OctoPackPublishApiKey=API-ABCDEFGHIJLKMNOP
Octopack and .NET Core
Octopack is not supported for .NET Core and we suggest using the VSTS extensions instead.
Add Steps to your Build or Release Process
Build or Release steps
The following steps can all be added to either your Build or Release process, depending on which you prefer.
To add a step to your Build process, edit your Build Definition and click Add build step.
To add a step to your Release process, edit your Release Definition, select the Environment, and click Add tasks.
Add a Package Application Step
If not using OctoPack
This step is only required if you are not using OctoPack to create your package.
Add a step to your Build or Release process, choose Package, click Add next to the Package Application task.
In the above image, the package version is defined as $(Build.BuildNumber). It's a common (and handy) practice to do this, and set the Build Number to be a format that corresponds to a valid NuGet version number.
We recommend you read the Build Versions in Team Build document for full details on versioning builds and packages.
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.
Add a Push Package(s) to Octopus Step
Add a step to your Build or Release process, choose Package, click Add the Push Packages(s) to Octopus task.
Add a Create Octopus Release Step
Add a step to your Build or Release process, choose Deploy, click Add next to the Create Octopus Release task.
Enabling the Include Changeset Comments and/or Include Work Items options will result in release notes which include deep-links into the TFS Work Items and Changesets.
Add a Deploy Octopus Release Step
Add a step to your Build or Release process, choose Deploy, click Add next to the Deploy Octopus Release task.
Add a Promote Octopus Release Step
Add a step to your Build or Release process, choose Deploy, click Add next to the Promote Octopus Release task.
Using the Dashboard Widget
On your VSTS 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.
In This Section
The following topics are explained further in this section: