Migrating webhooks from Kotlin Patch Files

When a webhook is edited (added, updated, deleted) and the project is stored as KotlinDSL, TeamCity will persist the differences in a patch file because it doesn't know how to convert Project Features into the tcWebHooks KotlinDSL.

Over time the project will have some webhook configuration in settings.kts, and any changes made in the UI will be stored in the patch files. This will become unmanageable. Wherever possible try to avoid making changes to WebHooks in the UI.

Warning: Patch files are hard to comprehend. Migration of simple patch files by hand might be possible. However, it is recommended to view the webhooks as Kotlin code, and copy those and then delete the patch entry.

Patch files are located inside a folder named patches. eg .teamcity/patches/projects/_Self.kts. A simple patch file looks like this:

package patches.projects

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.Project
import jetbrains.buildServer.configs.kotlin.ui.*

/*
This patch script was generated by TeamCity on settings change in UI.
To apply the patch, change the root project
accordingly, and delete the patch script.
*/
changeProject(DslContext.projectId) {
    features {
        remove {
            feature {
                type = "tcWebHooks"
                id = "PROJECT_EXT_5"
                param("authentication", "bearer")
                param("bearerPreemptive", "true")
                param("bearerToken", "dkfjsdlfjldfjk")
                param("buildAddedToQueue", "enabled")
                param("buildRemovedFromQueue", "enabled")
                param("buildTypes", "allProjectBuilds")
                param("subProjectBuilds", "true")
                param("template", "legacy-json")
                param("url", "http://localhost:8111/webhooks/endpoint.html?vcs_test=5")
                param("webHookId", "SmallKotlinProject_WebHook_05")
            }
        }
        add {
            feature {
                type = "tcWebHooks"
                id = "PROJECT_EXT_15"
                param("buildSuccessful", "enabled")
                param("subProjectBuilds", "true")
                param("template", "microsoft-teams-2")
                param("buildFailed", "enabled")
                param("webHookId", "id_836712707")
                param("buildTypes", "allProjectBuilds")
                param("enabled", "true")
                param("url", "http://localhost:8111/webhooks/endpoint.html?vcs_test=11")
            }
        }
    }
}

Looking at the above patch file, we have two changes to apply.

1. Delete the webhook with a webHookId of SmallKotlinProject_WebHook_05
2. Add a new webhook with url of http://localhost:8111/webhooks/endpoint.html?vcs_test=11

Deleting a webhook

To delete a webhook, find the webHookConfiguration in settings.kts with the correct webHookId and remove the whole block. Also look in the patch files and check if a matching record exists. If the webhookConfiguration is not in the settings.kts file, then it will probably exist in the patch file only.

Adding a webhook

To add a webhook, the simplest way is to edit the webhook in the UI and copy the Code into settings.kts. We can see the Kotlin code after clicking View as Code.