Specifying the maximum files listed in a change set

Since v1.1.355.396 and v1.2.0-alpha.4

When tcWebHooks processes the build object to create the payload for a webhook, it generates a changes object which contains an array of the changes relevant to the build. See the following example:

    "changes": [
      {
        "version": "fff02ffeedaef9adf5efe81bb485cb56a58c3f5d",
        "change": {
          "files": [
            "tcwebhooks-core/src/main/java/webhook/teamcity/payload/content/WebHookPayloadContent.java",
            "tcwebhooks-core/src/main/java/webhook/teamcity/payload/content/WebHooksChange.java",
            "tcwebhooks-core/src/main/java/webhook/teamcity/payload/content/WebHooksChangeBuilder.java",
            "tcwebhooks-core/src/test/java/webhook/teamcity/payload/content/WebHookPayloadContentChangesTest.java"
          ],
          "comment": "Add ability to limit or exclude vcs file list whilst building payload",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      },
      {
        "version": "d489de89fa31a7db23e7cc2a98e347dd175ed0a0",
        "change": {
          "files": [
            "tcwebhooks-core/src/main/java/webhook/teamcity/payload/content/WebHookPayloadContent.java"
          ],
          "comment": "Use java 7 for 1.1.x.x",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      },
      {
        "version": "c72e4a7cd653e6651d2931ce3c5d53fb7ee3274c",
        "change": {
          "files": [
            "tcwebhooks-core/src/main/java/webhook/teamcity/BuildStateEnum.java",
            "tcwebhooks-core/src/main/java/webhook/teamcity/payload/content/WebHookPayloadContent.java"
          ],
          "comment": "Set \"running\" status to something relevant to result.\n\nAddresses issue #138",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      }
    ]

In the above example, there are three changes, with a few files each. A total seven changed files in this changeset. However, for a large branch rebase or branch copy, this set of files can number in the thousands.

When the change set is large, it is expensive to generate the changed file list and produces a very large webhook payload.

Since v1.1.355.396 the behaviour has changed to only include the list of files if the total file count is 100 or less. Otherwise, the files object will be null, and will therefore not be serialised by the JSON parser.

If the above change set had included 101 or more files, the resulting payload would like look the following:

    "changes": [
      {
        "version": "fff02ffeedaef9adf5efe81bb485cb56a58c3f5d",
        "change": {
          "comment": "Add ability to limit or exclude vcs file list whilst building payload",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      },
      {
        "version": "d489de89fa31a7db23e7cc2a98e347dd175ed0a0",
        "change": {
          "comment": "Use java 7 for 1.1.x.x",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      },
      {
        "version": "c72e4a7cd653e6651d2931ce3c5d53fb7ee3274c",
        "change": {
          "comment": "Set \"running\" status to something relevant to result.\n\nAddresses issue #138",
          "username": "netwolfuk",
          "vcsRoot": "github-tcwebhooks"
        }
      }
    ]

As indicated above, in the cases where the change list is disabled or too large, the payload will contain a null files list. This is preferable to returning an empty list, because the empty list implies no actual changed files were included in the change. A null change list will typically be serialised to nothing in JSON or XML, so the json array or xml element will be missing from the payload. If your endpoint is expecting these, then it should fail in this scenario or handle the missing field gracefully.

Control the maximum number of files changed in a build before the changed file list is null. This can be controlled in the three ways below, in order of priority.

1. Add a 'param' named 'maxChangeFileListSize' to a webhook config by editing plugin-settings.xml
2. Add a build parameter to a buildType or project called 'webhook.maxChangeFileListSize'
3. Define a property in teamcity's internal properties file called 'webhook.maxChangeFileListSize'

If the total number of files is greater than maxChangeFileListSize, then the change list will be null.

Value	Effect
0	The files array will not be included (null). This effectively disables the file list.
100 (default)	A change set of 100 or less files will contain a files array which contains the list of files in the change. For change sets larger than this value, the files array will be null.
-1	All files will be included in the files array, regardless of the file list. This re-instates the old behaviour and is not recommended.