Creating WebHooks In a Versioned Settings enabled Project

When we store our project settings with Versioned Settings enabled, we tend to maintain our settings in Kotlin or XML format in a VCS repository. There are a couple scenarios here to discuss.

Settings are stored in VCS and TeamCity is allowed to update VCS when changes occur in the UI.
Settings are stored in VCS and TeamCity is not permitted to update the VCS when changes occur in the UI.

TeamCity is allowed to update VCS when changes occur in the UI

In this scenario, the following setting is enabled in the Versioned Settings section of the project configuration.

TeamCity will attempt to make commits to the repository whenever a change is made in the UI. I have had some success with this method, but have found that occasionally TeamCity will miss updates and fail to commit them to the VCS. I tend to watch the logs for teamcity-versioned-settings.log or the updates in the Versioned Settings page to be sure that the change has been applied. If no change is committed, try editing the webhook in the UI and saving it again.

TeamCity is not permitted to update the VCS when changes occur in the UI

This seems to be the recommended way to manage settings from a Versioned Settings project. Possibly due to the issues mentioned above. However, tcWebHooks does not currently support this very well. :-( This will be fixed in version 3.0 of tcWebHooks.

In version 2.x.x we have the following known issues.

tcWebHooks will let you edit the WebHooks in the UI, and they will appear to be persisted, but will disappear after the project is reloaded from VCS or TeamCity restarts.
Editing webhooks in the VCS is possible, but isn't very user friendly.
Webhooks edited in the VCS that don't have ID values will be recreated on every VCS commit, and only the latest one will work correctly. These are referred to in issue #246 as "ghost webhooks".

Editing webhooks in the VCS (tcWebHooks 2.x.x)

tcWebHooks stores the webhook configurations in the plugin-settings.xml file. In a Kotlin VCS project, this file is stored in the following locations.

.teamcity/pluginData/_Self/plugin-settings.xml - when the webhook is configured for the project that has VCS settings enabled.
.teamcity/pluginData/VcsSubProject0001/plugin-settings.xml - when the webhook is configured for a subproject of the project that has VCS settings enabled. In this example, the project's Project ID is VcsSubProject0001.

Edit then Download, or Edit and then Copy and Paste

It's possible to edit or create a webhook, find the settings and copy them to the file inside the VCS and paste it in.

Once edited from the UI, the plugin-settings.xml file is located on the server in the BuildServer/config/projects/ProjectIdentifer/pluginData/plugin-settings.xml. See screenshot below.

Clicking the file allows previewing and downloading the file.

The file can be simply downloaded and saved into the relevant location in the configuration repository. For example into .teamcity/pluginData/_Self/plugin-settings.xml. Alternatively, the contents of the file (or just part of the file) can be copied and pasted into the plugin-settings.xml file in the VCS settings repo and committed.

Edit the file by hand

The other way to add or edit a webhook is to edit the plugin-settings.xml file directly in the VCS repo. The file is XML and contains all settings for all plugins that use the (now old) plugin-settings format.

The following is an example XML file showing just webhooks. Note: It is possible that other plugins could be using this file too, however most plugins appear to have migrated to the new style of saving settings known a ProjectFeatures. This is planned for tcWebHooks version 3.x.x

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
    <webhook id="VCSProjectTop_WebHook_01" enabled="true" template="legacy-xml" hide-secure-values="true"
             url="http://localhost:8111/webhooks/endpoint.html?project=VCSProjectTop">
      <states>
        <state type="buildAddedToQueue" enabled="false" />
        <state type="buildRemovedFromQueue" enabled="false" />
        <state type="buildStarted" enabled="true" />
        <state type="changesLoaded" enabled="true" />
        <state type="buildInterrupted" enabled="true" />
        <state type="beforeBuildFinish" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildSuccessful" enabled="true" />
        <state type="buildFailed" enabled="true" />
        <state type="buildFixed" enabled="false" />
        <state type="buildBroken" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="buildPinned" enabled="false" />
        <state type="buildUnpinned" enabled="false" />
        <state type="testsMuted" enabled="false" />
        <state type="testsUnmuted" enabled="false" />
        <state type="reportStatistics" enabled="false" />
        <state type="serviceMessageReceived" enabled="false" />
      </states>
      <parameters>
	<param name="color" value="red" />
	<param name="notify" value="1" />
	<param name="branchName" value="${branchDisplayName}"
               secure="false" included-in-legacy-payloads="true"
               force-resolve-teamcity-variable="true" template-engine="VELOCITY" />
      </parameters>
      <auth type="bearer" enabled="true" preemptive="true">
        <auth-parameters>
          <param name="bearer" value="${test.thing1}" />
        </auth-parameters>
      </auth>
      <headers>
        <header name="zxc" value="zxczxczxcxzc" />
      </headers>
      <trigger-filters>
        <filter value="${branchDisplayName}" regex="^master$" enabled="true" />
        <filter value="${buildInternalTypeId}" regex="^bt\d$" enabled="true" />
      </trigger-filters>
      <build-types enabled-for-all="false" enabled-for-subprojects="true">
        <build-type id="bt1" />
        <build-type id="bt2" />
      </build-types>
    </webhook>
  </webhooks>
</settings>

Provide feedback

Saved searches