Skip to content

Manually Migrating WebHooks

Jump to bottom Edit New page
netwolfuk edited this page Aug 29, 2025 · 26 revisions

This page details the process of manually migrating webhooks. Typically, this is from the v2 format (plugin-settings.xml) to the v3 format (ProjectFeatures).

For most users, the webhooks will be migrated automatically the first time the v3 plugin starts. However, there are scenarios when this does not work.

Migration Processes

Adding Configurations to settings.kts

Each webhook is declared using the webHookConfiguration function inside a features block in the project's settings.kts file.

For details see:

Adding Configurations to project-config.xml

WebHooks are stored as Project Features in the project-config.xml. This is an XML representation of a Map (dictionary) of name/value pairs that define the attributes of a webhook.

See other items on this page for instructions on how to generate these XML elements. Writing them by hand is not easy.

Removing old webhooks from plugin-settings.xml

Within the repository, there will be plugin-settings.xml files for each project. There may be sub-projects within the same repository. Each webhook found in each of these files will need to be migrated to the settings.kts.

image

Once migrated, the <webhooks> element can be removed from these files. If there is no other plugin configurations in these plugin-settings.xml files, the file can be completely removed.

Migration Scenarios

Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is disabled.

It is not possible for tcWebHooks to migrate webhooks into VCS automatically. The settings.kts file must be manually updated in the kotlin DSL format. Fortunately tcWebHooks can generate the KotlinDSL for these webhooks to ease the process of generating valid Kotlin configurations.

  1. The migration report generated on first run should contain example KotlinDSL configurations for existing webhooks. They are grouped together in the file for each project.
  2. Visiting /webhooks/migration.html?project=MyProjectId in TeamCity will display KotLin configurations for all webhooks found in plugin-settings.xml. Note: Replace MyProjectId with the project Id of the relevant TeamCity project.

The follow the directions on:

Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is enabled.

Although it is possible to migrate settings, the changes are created as "patch" files in the repository as a set of Name/Value pairs in a strange kotlin object.

The settings.kts file must then be manually updated in the kotlin DSL format based on the input from the diff files. This is not very user friendly, and it's better to just generate the webhook configuration in Kotlin from the plugin settings. For this reason migrations are not attempted automatically for KotlinDSL projects.

Fortunately tcWebHooks can generate the KotlinDSL for these webhooks to ease the process of generating valid Kotlin configurations.

  1. The migration report generated on first run should contain example KotlinDSL configurations for existing webhooks. They are grouped together in the file for each project.
  2. Visiting /webhooks/migration.html?project=MyProjectId in TeamCity will display KotLin configurations for all webhooks found in plugin-settings.xml. Note: Replace MyProjectId with the project Id of the relevant TeamCity project.

The follow the directions on:

Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is enabled. I have a patch file.

This means that webhook changes have been made in the UI and TeamCity has peristed those changes into a patch file because it doesn't know how to convert Project Features into the tcWebHooks KotlinDSL. This is a known shortcoming of the KotlinDSL format.

For full details on migrating patch contents, please see Migrating webhooks from Kotlin Patch Files

Project Settings are stored in VCS as XML. Allow editing project settings via UI is disabled.

It is not possible for tcWebHooks to migrate webhooks into VCS automatically. The project-config.xml file must be manually updated in in XML format. Fortunately tcWebHooks can generate the project features as XML for these webhooks to ease the process of generating valid XML configurations.

  1. The migration report generated on first run should contain example XML configurations for existing webhooks. They are grouped together in the file for each project.
  2. Visiting /webhooks/migration.html?project=MyProjectId in TeamCity will display XML configurations for all webhooks found in plugin-settings.xml. Note: Replace MyProjectId with the project Id of the relevant TeamCity project.

The follow the directions on:

Add a custom footer
Clone this wiki locally