Skip to content

Release Notes for version 3

Jump to bottom Edit New page
netwolfuk edited this page Jul 15, 2025 · 18 revisions

New Features in tcWebHooks v3

  • Automatic Migration from old style (Plugin Settings) to new style (ProjectFeatures) (except for Settings stored in VCS)
  • KotlinDSL for configuration of webhooks from code (if you use it).
  • Logging entries in teamcity-server.log are now prefixed with jetbrains.buildServer.SERVER.tcWebHooks. This allows using a log4j configuration that sets just tcWebHooks to DEBUG

ProjectFeatures migration

Originally, TeamCity supported the configuration of plugins using a plugin-settings.xml file for each project. This was an XML file for which the plugin developer had full control over the schema of their plugin's configuration.

Over time, TeamCity started recommending ProjectFeatures and moving away from plugin-settings.xml. However, this format only supports reading and writing to a list of Key/Value pairs. I felt this was a major limitation.

The time has come to migrate to using ProjectFeatures. There are two main reasons:

  • Support for webhooks configuration via KotlinDSL.
  • Work around a long standing bug where TeamCity does not reliably load plugin-settings.xml. This one causes clustered TeamCity instances to forget all the WebHooks when a node fails over.

Goodbye plugin-settings.xml. Hello project-config.xml

The webhooks node in the plugin-settings.xml file previously looked like the example webhook in plugin-settings.xml.

Since tcWebHooks 3.0.0, webhook configurations are now stored in the project's project-config.xml as per the example file. This is a technical detail about where the configuration is stored. If we just use TeamCity and manage all our settings from the UI, we can simply continue to configuring webhooks the same as before, and our existing webhooks should be migrated to the new format.

Managing WebHooks using the KotlinDSL

If we're using a KotlinDSL to define our TeamCity project config, we should also specify our WebHooks in the tcWebHooks KotlinDSL format. We can see the same webhook as above configured in the Example-settings.kts file.

Conversion to using Project Features

For most users, our webhooks should be automatically converted from plugin-settings.xml to project-config.xml. This process happens the first time the version 3 plugin starts up.

The migration tool does the following:

  1. Assembles list of projects
  2. Checks for existing webhook file in each project's plugins settings directory.
  3. Read file and check if webhooks are found.
  4. If webhooks enabled, and webhooks count > 0
  5. Backup file with name like plugin-settings-tcWebHooks-backup-yyyy-MM-dd_HH-mm-ss.xml from LocalTime. Do the following for each project with webhooks.
    • Load old configs.
    • Iterate over each webhook
      • call addNewWebHook
      • remove from WebHookPluginSettings internal map.
    • Call persist on each project. This will remove the webhook from the previous settings file.
  6. Add a setting to config/internal.properties for teamcity.plugin.tcWebHooks.pluginSettingsToProjectFeaturesMigation=completed

A migration report is written in DataDir/system/tcWebHooks-ProjectFeatures-migration-report-YYYY-MM-dd_HH-MM-SS.txt. This file logs the migration process, which parts were successful, and example of manual edits that will need to be made.

It is expected that migration will be successful except for projects that store their configuration settings in VCS. For those projects, webhooks will need to be manually migrated and committed to the VCS.

image

Example Migration Report

Starting PluginSettings To ProjectFeatures Migration at 2025-07-01_21-45-48
----------------------------------------------------------------------------------------
2025-07-01 21:45:48.919 : The following projects has been selected for migration: _Root, TcPlugins, TcPlugins_TestProjects


2025-07-01 21:45:48.920 : Starting migration of project '_Root'. There are '3' webhooks to migrate
2025-07-01 21:45:48.927 : Backed up existing plugin-settings.xml file in project '_Root'. Copied from '/data/teamcity_server/datadir/config/projects/_Root/pluginData/plugin-settings.xml' to '/data/teamcity_server/datadir/config/projects/_Root/pluginData/plugin-settings-2025-07-01_21-45-48.xml'
2025-07-01 21:45:48.927 : Existing webhook IDs in ProjectFeatures: 
2025-07-01 21:45:48.928 : Existing webhook IDs in ProjectSettingsManager: id_590012931, id_850041933, id_32319229
2025-07-01 21:45:48.928 : Existing webhook IDs found in plugins-settings.xml file: id_590012931, id_850041933, id_32319229
2025-07-01 21:45:48.946 : Copied webHook to ProjectFeatures. Id: 'id_590012931', Project: '_Root'
2025-07-01 21:45:48.946 : Deleted webHook from PluginSettings. Id: 'id_590012931', Project: '_Root'
2025-07-01 21:45:48.949 : Copied webHook to ProjectFeatures. Id: 'id_850041933', Project: '_Root'
2025-07-01 21:45:48.949 : Deleted webHook from PluginSettings. Id: 'id_850041933', Project: '_Root'
2025-07-01 21:45:49.041 : Copied webHook to ProjectFeatures. Id: 'id_32319229', Project: '_Root'
2025-07-01 21:45:49.041 : Deleted webHook from PluginSettings. Id: 'id_32319229', Project: '_Root'


2025-07-01 21:45:49.105 : Starting migration of project 'TcPlugins'. There are '3' webhooks to migrate
2025-07-01 21:45:49.110 : Backed up existing plugin-settings.xml file in project 'TcPlugins'. Copied from '/data/teamcity_server/datadir/config/projects/TcPlugins/pluginData/plugin-settings.xml' to '/data/teamcity_server/datadir/config/projects/TcPlugins/pluginData/plugin-settings-2025-07-01_21-45-48.xml'
2025-07-01 21:45:49.110 : Existing webhook IDs in ProjectFeatures: 
2025-07-01 21:45:49.110 : Existing webhook IDs in ProjectSettingsManager: id_639824763, id_447619007, id_403428612
2025-07-01 21:45:49.111 : Existing webhook IDs found in plugins-settings.xml file: id_639824763, id_447619007, id_403428612
2025-07-01 21:45:49.113 : Copied webHook to ProjectFeatures. Id: 'id_639824763', Project: 'TcPlugins'
2025-07-01 21:45:49.113 : Deleted webHook from PluginSettings. Id: 'id_639824763', Project: 'TcPlugins'
2025-07-01 21:45:49.116 : Copied webHook to ProjectFeatures. Id: 'id_447619007', Project: 'TcPlugins'
2025-07-01 21:45:49.116 : Deleted webHook from PluginSettings. Id: 'id_447619007', Project: 'TcPlugins'
2025-07-01 21:45:49.120 : Copied webHook to ProjectFeatures. Id: 'id_403428612', Project: 'TcPlugins'
2025-07-01 21:45:49.120 : Deleted webHook from PluginSettings. Id: 'id_403428612', Project: 'TcPlugins'


2025-07-01 21:45:49.210 : Starting migration of project 'TcPlugins_TestProjects'. There are '2' webhooks to migrate
2025-07-01 21:45:49.213 : Backed up existing plugin-settings.xml file in project 'TcPlugins_TestProjects'. Copied from '/data/teamcity_server/datadir/config/projects/TcPlugins_TestProjects/pluginData/plugin-settings.xml' to '/data/teamcity_server/datadir/config/projects/TcPlugins_TestProjects/pluginData/plugin-settings-2025-07-01_21-45-48.xml'
2025-07-01 21:45:49.213 : Existing webhook IDs in ProjectFeatures: 
2025-07-01 21:45:49.213 : Existing webhook IDs in ProjectSettingsManager: id_284671024, id_409020859
2025-07-01 21:45:49.213 : Existing webhook IDs found in plugins-settings.xml file: id_284671024, id_409020859
2025-07-01 21:45:49.214 : Copied webHook to ProjectFeatures. Id: 'id_284671024', Project: 'TcPlugins_TestProjects'
2025-07-01 21:45:49.214 : Deleted webHook from PluginSettings. Id: 'id_284671024', Project: 'TcPlugins_TestProjects'
2025-07-01 21:45:49.215 : Copied webHook to ProjectFeatures. Id: 'id_409020859', Project: 'TcPlugins_TestProjects'
2025-07-01 21:45:49.215 : Deleted webHook from PluginSettings. Id: 'id_409020859', Project: 'TcPlugins_TestProjects'


2025-07-01 21:45:49.276 : tcWebHooks PluginSettings to ProjectFeatures migration completed see '/data/teamcity_server/datadir/system/tcWebHooks-ProjectFeatures-migration-report-2025-07-01_21-45-48.txt' for a report.

Migration Status tab in TeamCity's Administration Page

For administrators, a new tab has been added named WebHooks Migration. This page shows the migration status of every project.

image

Per project Migration information

Clicking into a project shows examples of any configurations that need to be manually updated. This project specific page should be able to be shared with your teams. They don't need administrator access to TeamCity, just EDIT_PROJECT permission on that specific project. Any existing webhooks read from plugin-seetings.xml are converted to the relevant format (KotlinDSL or ProjectFeatures XML) and displayed on the page. These will need to be copied into the VCS Settings repo and committed so that TeamCity can load them.

Please see the Manually Migrating WebHooks page for details on this process.

image

Add a custom footer
Clone this wiki locally