There are two plugins that work hand-in-hand to enable TeamCity builds with changes from a Phabricator code review. If you are unfamiliar to [Phabricator](https://www.phacility.com/phabricator/) and their terminologies see the **Background** section below for an overview.
The Phabricator Software Development Suite has the ability for code review, CI & CD along side numerous other development tools.
Phabricator code reviews are called [_Differential Revisions_](https://www.phacility.com/phabricator/differential/). Phabricator differs to other code review workflows because they are pre-commit reviews and therefore the changes that are getting peer reviewed are not in version control. This gives Phabricator a _write_, _review_, then _merge_ workflow, which is different than most pull-request methodologies such as GitHub. In this workflow our code changes are managed by Phabricator and are not in version control during the code review process for us to build with CI.
To trigger a _Differential Revision_ (code review) a command line tool called [_Arcanist_](https://www.phacility.com/phabricator/arcanist/) is used. This tool handles the interaction with Phabricator to request, update and merge code reviews. An example of putting code up for review would be running _Arcanist_ like: `arc diff`. This would essentially mimic pushing a feature branch and creating a PR. If another developer wanted to pull down a copy of the changes to review in-depth they would also use _Arcanist_ to patch in the changes: `arc patch <Differential ID>`.
When a _Differential Revision_ is created, Phabricator has the ability to to trigger CI "builds" with the changes, this feature is called _Harbormaster_. These _Harbormaster_ builds usually trigger other build systems which report back the results, one of the in-built triggers is for Jenkins. There is **no** inbuilt trigger for TeamCity.
## Why TeamCity Phabricator Plugins
As outlined above, Phabricator does not have a default trigger for TeamCity. To add a TeamCity trigger we have extended Harbormaster with `Harbormaster-Teamcity-Plugin` which adds the relevant files to communicate with TeamCity to run build configurations. The plugin also sends additional information to TeamCity for the partner plugin to use when reporting the result back to Phabricator.
Since code review changes are not in version control we cannot rely on TeamCity to patch in the changes using Git. We needed to create a plugin that listened and identified builds triggered by `Harbormaster-Teamcity-Plugin` and then utilise _Arcanist_ to patch in the exact changes that need to be built before reporting the result back to Phabricator.
To deploy simply copy the contents of the `Harbormaster-Teamcity-Plugin` folder in to `src/extensions/` on the Phabricator instance and then restart the application. Currently there are only three files that need to be transfered: `HarbormasterTeamCityBuildStepImplementation.php`, `PassphraseTokenKey.php`&`TeamCityXmlBuildBuilder.php`.
The TeamCity plugin comprises of server and agent plugins for TeamCity. Together they collate the information sent from `Harbormaster-Teamcity-Plugin` and run _Arcanist_ to pull in the changes from the associated _Differential Revision_.
To deploy, upload the `Teamcity-Phabricator-Plugin-<version>.zip` on TeamCity's plugin administration page.
This will install the **Phabricator Plugin** build feature that can be enabled per build configuration used for _Differential Revisions_.
* To build the plugins (server and agent) just run: `mvn clean compile package`
By default the TeamCity plugin is equipped with `teamcity-sdk-maven-plugin` which allows for developing against a local instance of TeamCity with debugging capabilities. See their documentation for how to use: https://github.com/JetBrains/teamcity-sdk-maven-plugin
## Future Development:
* Look for _Arcanist_ on the path rather than hard-coding it.
* Report back unit tests
## Credits
The inspiration for the plugin is from https://github.com/halfmatthalfcat/TeamCity-Phabricator-Plugin which is no longer maintained. We have reused the Harbormaster files from the original authors repository.
