This plug-in allows TeamCity builds to trigger deployments in Octopus Deploy.

Get the plugin

Download the plugin from the Octopus Deploy downloads page or the JetBrains plugins downloads.

Installation and usage instructions are available in the Octopus Deploy documentation.

Building

To build the plugin from code:

1. Install the latest version of the JDK (plugin is build/runnable in Java-8 and above)
2. Install TeamCity
3. Run gradlew clean distZip
   The gradlew script will download Gradle for you if it is not already installed.
4. The plugin is available at build/distributions/Octopus.TeamCity.<X.Y.Z>.zip (where X.Y.Z is the SemVer of the release, potentially including 'SNAPSHOT').

Editing and debugging in IntelliJ

1. Set the following environment variables to enable debug into Server/Agent and also enable "devMode" in the server, which expedites development by allowing 'hot-reload' of both plugins and Java Server Pages (JSP files). It also ensures the new Octopus Step Vnext is available (feature flagged).
   1. TEAMCITY_SERVER_OPTS=-Dteamcity.development.mode=true -agentlib: jdwp=transport=dt_socket,server=y,suspend=n,address=*:5011 -Denable.step.vnext=true
   2. TEAMCITY_AGENT_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5010
2. Install TeamCity locally to C:\TeamCity. Allow the service to start for the first time, and add an admin user. Then stop the service so it is not running.
3. Give yourself full permissions to the Teamcity Data folder (usually C:\ProgramData\JetBrains\TeamCity). This folder may be hidden.
4. Import the Gradle project into IntelliJ.
5. Two Run Configurations 'AttachToServer' and 'AttachToAgent' should already exist - and allow the IDE to connect to running, debug-enabled

Start a Teamcity server and agent manually, then install the built plugin via the administration-> plugins menu option.

You can then attach to the server/agent via the provided run-configurations, and step through the plugin code when build steps are configured (on server) or executed (on agent).

Build Server

The TeamCity Plugin uses Github actions for all CI/CD/Release operations.

Updating the version of Octopus CLI we embed

Note that OctopusCLI has been deprecated in favour of the newer CLI which is written in Go. Due to compatibility issues with the new CLI, this plugin should continue to use OctopusCLI.

If the Octopus CLI has changed such that we need to update the version we embed with the plugin the steps are as follows:

• Locate the latest release of the CLI on the OctopusCLI repo
• Download the OctopusTools.[version].win-x64.zip package and extract the octo.exe from it
• Also download the OctopusTools.[version].portable.zip file
• Rename the latter to OctopusTools.portable.zip and then copy them into the \octopus-agent\src\main\resources\resources\3\0 folder, over the existing files

Using Docker

Some docker files have been provided to assist development for users who may not have all the prerequisite tooling available on their local machine for development. This process will currently be slower and does not provide the benefits of debugging at this point in time.

1. Run docker-compose -f docker-compose.teamcity.yml up -d to allow the TeamCity server and agent spin up. This will take some time to initialize and will store the configuration files under ./docker-files. This will allow for both restarting the server without the full initialization and to pass in the Octopus plugin.
2. Once the server has started navigate, to the instance via http://localhost:8111 and create an admin login (this setup only needs to take place once due to the configuration mount). Once the server starts up, navigate to Agents->Unauthorized and authorise the agent that was started in a container alongside the server.
3. Build the plugin by running docker-compose -f docker-compose.build.yml up. This will use a gradle image, mount the current directory and invoke the gradlew command described above. At the end of the build the plugin will be copied into the TeamCity plugins directory created by the container in the previous step.
4. Once the plugin has been built, you will need to restart the server by running (depending on your environment) docker restart octopus-teamcity_teamcity-server_1.
5. When testing with a connection to an Octopus Server instance on your local host instance, you can use the special host.docker.internal route. e.g. http://host.docker.internal:8065

End-2-End Tests

The e2e suite spins up real TeamCity + agent + free-tier Octopus + MSSQL containers via Testcontainers (Docker). To run it:

./gradlew :e2e:playwrightInstall   # once — only for the Playwright UI tests
./gradlew :e2e:e2eTest             # run the suite (add --tests "*SomeTest" for one)

On macOS/Windows, run it inside the provided Linux container instead so the Playwright UI tests work:

docker compose -f e2e/docker-compose.yml up --abort-on-container-exit --exit-code-from e2e

See docs/e2e-tests.md for prerequisites, the TEAMCITY_PLUGIN_DIST and GRADLE_TESTS options, how to add a test, and interactive manual testing.

Versioning, Releasing and Publishing

The version is computed from git, and releases are cut by release-please from Conventional Commit messages.

Versioning

The plugin version for a build is computed by GitVersion (GitVersion.yml, mode: ContinuousDeployment) and passed to Gradle as -Pversion=<computed>: pull-request builds get a pre-release version (e.g. 6.3.1-PullRequest0192.31) and release builds get the tagged version. The version in gradle.properties is the fallback for local builds (./gradlew distZip with no -Pversion).

Releasing

Releases are driven by Conventional Commit messages and the release-please workflow (.github/workflows/release.yml, run on each push to main):

1. Land changes on main via PRs with Conventional Commit messages: fix: bumps the patch, feat: the minor, and !/BREAKING CHANGE: the major (docs:, style:, test:, chore: don't bump the version).
2. release-please maintains a release PR that bumps the version and updates CHANGELOG.md.
3. Merging the release PR creates the git tag (vX.Y.Z) and the GitHub Release.

Publishing

Publishing the GitHub Release triggers the build workflow (.github/workflows/main.yml, on release: [published]), which builds and tests at the release version and creates a release in Octopus Deploy.

The package reaches the JetBrains Marketplace via Octopus Deploy: promoting the TeamCity Plugin from "Components - Internal" to "Components - External" runs a script that pushes the package to JetBrains.