Manually Migrating WebHooks

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.

• Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is disabled.
• Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is enabled.
• Project Settings are stored in VCS as Kotlin. Allow editing project settings via UI is enabled. I have a diff file.
• Project Settings are stored in VCS as XML. Allow editing project settings via UI is disabled.
• Project Settings are stored in VCS as XML. Allow editing project settings via UI is enabled.
• Project Settings are not stored in VCS. Some or all webhooks have vanished from the UI.
• Project Settings are not stored in VCS. There are unexpected (ghost) webhooks showing in the UI.

Migration Processes

Adding Configurations to settings.kts

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.

Once migrated, the <webhooks> element can be removed from these files. If there is no other plugin configurations in these plugin-settings.xml file, they 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:

• Adding Configurations to settings.kts
• Removing old webhooks from plugin-settings.xml

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 "diff" 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:

• Adding Configurations to settings.kts
• Removing old webhooks from plugin-settings.xml