TeamCity On-Premises 2024.03 Help

Running Personal Build

A personal build is a build-out of the common build sequence which typically uses the changes not yet committed into the version control. Personal builds are usually initiated from one of the supported IDEs via the Remote Run procedure. You can also upload a patch with changes directly to the server, as described below.

A personal build uses the current VCS repository sources plus the changed files identified during the remote run initiation. The results of a personal build can be seen in the "My Changes" view of the corresponding IDE plugin and on the Changes page in TeamCity. Finished personal builds are listed in the build history, but only for the users who initiated them.
Read more about running commits via Remote Run in Pre-Tested (Delayed) Commit.

By default, users only see their own personal builds in the build lists, but this can be changed via the "Show all personal builds" option in Your Profile | General | UI settings of the user profile.

You can also mark a build as personal using the corresponding option of the Run dialog.
By default, only users with the Project Developer role can initiate a personal build.

It is possible to restrict running personal builds in the General Settings of a build configuration.

Direct Patch Upload

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.

    Upload a unidiff patch via UI
  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.

Promoting Personal Build

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.

Triggering Personal Build Chain

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.

Run Build on Perforce Shelved Files

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.

Last modified: 25 October 2022