TeamCity from JetBrains is a popular continuous integration server that supports a variety of different version control systems and build runners. Octopus Deploy and TeamCity can work together to make automated, continuous delivery easy.
When using Octopus Deploy with TeamCity, TeamCity will usually be responsible for:
- Checking for changes in source control.
- Compiling the code.
- Running unit tests.
- Creating NuGet packages for deployment.
While Octopus Deploy will be used to take those NuGet packages and to push them to development, test and production environments.
Integration with TeamCity involves two major parts:
- Creating the NuGet packages from your applications.
- Optionally, when a build completes, having TeamCity make requests to your Octopus Server to:
- Create releases
- Trigger deployments and/or
- Promote releases when a build completes
Installing the Plugin
To make integrating with TeamCity easy, a plugin is available from our download page. The plugin is distributed as a ZIP file. To install:
- Download the TeamCity Plugin ZIP file.
- Shut down your TeamCity server.
- Copy the ZIP file with the plugin to
<TeamCity Data Directory>/plugins.
- Start TeamCity server: the plugin files will be unpacked and processed automatically.
The TeamCity Data Directory can be found on the Administration | Global Settings page for a running TeamCity server instance.
Creating Octopus-compatible NuGet Packages Using TeamCity
Octopus requires that you package your applications into NuGet packages, whether or not you are using TeamCity. There are many ways to create Octopus-compatible NuGet packages, but the easiest way is with OctoPack.
For more information on using OctoPack to create NuGet packages, see using OctoPack.
When you set up your build configuration in TeamCity, use either the MSBuild runner or the Visual Studio build runner. At the bottom of the runner settings, you'll see some options to run OctoPack during the build:
The OctoPack package version setting should evaluate to a version number with multiple parts (e.g., 1.3.7). It cannot be a single number. You may want to edit the General Settings for your project to ensure that the TeamCity build number uses multiple parts:
With these options selected, NuGet packages will automatically be created using the version number of the current build. OctoPack will ensure that these packages appear in the artifacts tab of TeamCity:
Can't use OctoPack?
Don't worry, TeamCity comes with a built-in NuGet Pack build step that you can use to package up Octopus-compatible NuGet packages. Just point it to your .csproj file, or a .nuspec file and TeamCity will package up your project for you. Just be aware that OctoPack has extra features (like adding website content files by convention) but at the end of the day it's just producing a NuGet package.
Using Octopus as a Package Repository
Octopus can be used as a NuGet package package, or can be configured to use an external feed (such as retrieving them from TeamCity).
To push packages to Octopus during the OctoPack phase, enter the NuGet endpoint url into the Publish packages to http field, and an API key in the Publish API Key field. OctoPack will then push the packages when the solution is built. You'll find the URL to your repository on the Library ➜ Packages tab in Octopus. Simply click the
Show examples link to see options to upload packages including the repository URL.
Consuming the TeamCity NuGet feed in Octopus
Octopus 2.x-3.3.x will work with TeamCity 7.0 or newer.
Octopus 3.4+ requires TeamCity 9.0+ due to compatibility problems with the older NuGet v1 feed implemented by earlier versions of TeamCity. Refer to this thread and this GitHub Issue for more details.
TeamCity 7 and up can act as a NuGet repository. You can enable this by going to the Administration➜NuGet Settings page, and enabling the inbuilt NuGet server. Any build artifacts ending with
.nupkg will automatically be served as NuGet packages, which Octopus can consume.
To connect Octopus to your TeamCity server, add the TeamCity authenticated feed URL to your NuGet settings in Octopus on the External Feeds tab under the Library page.
Once added, the TeamCity feed will appear in the NuGet feed list:
You can use the Test link to make sure that the NuGet package is available, before creating your Octopus project:
Tip: delayed package publishing
NuGet packages created from your build won't appear in the TeamCity NuGet feed until after the build fully completes. If you plan to trigger a deployment during a build, this creates a problem: the package won't be in the feed until the build is published, so you won't be able to deploy it.
The solution is to configure a secondary build configuration, and use a snapshot dependency and build trigger in TeamCity to run the deployment build configuration after the first build configuration completes. The video below demonstrates how to do this.
Creating and Pushing Packages From TeamCity to Octopus
In version 4.38.0 of the TeamCity Plugin we have added a new build runner that can be used to package your applications as either a NuGet or Zip formatted package.
In version 3.3.1 of the TeamCity Plugin we have added a new build runner that can be used to package and push your applications from TeamCity to Octopus.
Triggering Deployments From TeamCity
The Octopus TeamCity plugin comes with these custom build runners:
- Octopus Deploy: Pack (TeamCity plugin 4.38.0 or newer) Create a NuGet or Zip formatted package.
- Octopus Deploy: Push Packages (Octopus 3.3 and TeamCity plugin 3.3.1 or newer) Push packages to the Octopus Deploy built-in repository, optionally using the TeamCity zip feature to create packages on-the-fly.
- Octopus Deploy: Create Release Creates a new release in Octopus Deploy, and optionally deploys it to an environment.
- Octopus Deploy: Deploy Release Deploys an existing release to a new environment.
- Octopus Deploy: Promote Release Promotes an existing release from one environment to another.
The plugin is simply a wrapper for Octo.exe, the Octopus command line tool for creating and deploying releases.
The video below is from a webinar hosted by JetBrains in which we demonstrated these features:
Using the Plugin With Linux Build Agents
Traditionally the Octopus TeamCity plugin required a Windows build agent to work. As of version 4.2.1 will run on Linux build agents if they meet either one of the following requirements:
- Have .NET Core installed on the build agent and in the PATH such that the
dotnetcommand runs successfully. To install, follow the linked guide to install the .NET Core SDK for your distribution. Ensure that the
dotnetcommand runs successfully. From version 4.15.10 of the plugin .NET Core v2 is required.
- Have the Octo command line tool installed and in the PATH such that the
Octocommand runs successfully. To install, download the .tar.gz for you system from the Octopus download page, extract somewhere appropriate and symlink
Octointo your PATH. Again, ensure that
Octoruns successfully. On Ubuntu you may need to install
libunwind8using your package manager