Running Personal Build

Users with the Change build source code with a custom patch permission can upload a patch with local changes directly to the TeamCity server, via our web UI or REST API.

TeamCity supports patches in a unified diff format.
Since the format varies between tools that can generate unidiff files, we cannot guarantee error-free processing of all unidiff variations. Currently, TeamCity provides a stable parsing of unidiff files generated by IntelliJ Platform IDEs and Git.
TeamCity does not support binary changes in non-binary files.

To generate a patch:

• In any IntelliJ Platform IDE: select the required local changes in the commit log, click Create Patch in the context menu, and save the patch as a *.diff file.

• Via Git: run git diff commit1..commit2 > path/filename.diff.
  For example, to save a diff between the last commit and the preceding commit to the patch.diff file in the test directory, run git diff HEAD^ HEAD > ~/test/patch.diff. See other examples in Git documentation.

To upload a patch and run a personal build via the web UI:

1. Open the Run Custom Build dialog and enable the " run as a personal build " option. The Upload patch button will appear.

   

2. Upload the patch and click Run Build.
   The agent will receive the patch and apply it before running the build. After the build, it will revert the patch, so the checkout directory can be reused by subsequent builds.

To upload a patch and run a personal build via REST API:

1. Send the following POST request:

   curl \
      -X POST \
      -H "Content-Type: text/text" \
      -H "Origin: <host>:<port>" \
      --data-binary @patch.diff \
      "http://<username>:<password>@<host>:<port>/uploadDiffChanges.html?description=<description-text>&commitType=0"

   As a response, you will receive the ID of this change on the server.

2. Create an XML file that describes the build node and mentions the build configuration ID and the ID of your personal change:

   <build personal="true">
     <triggered type='idePlugin' details='Unified Diff Patch'/>
     <triggeringOptions cleanSources="false" rebuildAllDependencies="false" queueAtTop="false"/>
     <buildType id="<build_configuration_id>"/>
     <lastChanges>
       <change id="<change_ID>" personal="true"/>
     </lastChanges>
   </build>

3. To trigger a personal build via REST API, post the created file to the buildQueue endpoint:

   curl \
       -X POST \
       -H "Content-Type: application/xml" \
       -H "Origin: <host>:<port>" \
       --data @node.xml \
       "http://<username>:<password>@<host>:<port>/app/rest/buildQueue"

   The agent will receive the patch and apply it before running the build. After the build, it will revert the patch, so the checkout directory can be reused by subsequent builds. Unused patches are automatically cleaned up by a 15-minutes timeout.

You can promote a personal build in the same way as a non-personal build. After promotion, the dependent build will be run as a personal one and use the same patch.

When a personal build chain is triggered, TeamCity will make all builds of the build chain personal and try to apply the personal patch to all of them. However, TeamСity will not apply the patch if the changes do not match checkout rules. For example, if a patch changes src/File.java but the VCS Checkout Rules configuration excludes the src folder, then the patch will not be applied, and the source code on the agent will not be changed. In this case, this build can be optimized to a non-personal build that checks out the same revision.

If the current build configuration has a Perforce VCS root, you can run a personal build based on changes in shelved Perforce files. For this, enable the run as a personal build option and enter the target changelist ID in the Shelved changelist ID field.

tip

Learn how to automate such builds.