My build light's TeamCity plugin spec and a sticky active branch problem
Hi
Sorry this is a rather long post but I’m writing a TeamCity plugin for our build light at http://www.thebuildlight.com/ and as it’s a light that (hopefully!) will go out to a diverse user base I want to make sure the we get it right and the plugin we build is true to TeamCity’s concepts. Also at the end of the post is a difficult active branch problem I can't solve on which I'd appreciate some advice.
I’ve a long history with CI but somehow managed to get through my development life without using TeamCity so am a bit of a newbie. Your tool is configurable (to say the least!) but I’ve spent a little time with it and think I now have enough of an idea to take a crack at specifying how the plugin should work. I’d really appreciate feedback on whether the scheme is true to your product and any other suggestions you’d be kind enough to supply.
I’ll break specification into 3 sections
- How the build light works
- TeamCity plugin functionality
- TeamCity plugin implementation
In a final section I’ll cover off a request I’ve had from one of my early adopters which has proven problematic.
How the build light works
The light comes with a series of plugins for a range of build tools (Jenkins, VSTS for example… and of course TeamCity!). At its core each plugin implements a simple method that returns a build status of either Broken or Ok. The light cycles through the configured plugins polling build statuses and if any return Broken the light goes red. Pretty simple really.
TeamCity plugin functionality
The intent is that the plugin be tightly tied to TeamCity’s configuration and not provide scope for yet another level of configuration over that supplied with TeamCity. We feel that will just confuse users and there’s more than enough configurability in TeamCity. On that basis there are 3 simple plugin configurations:
- Build Type Configuration: The light turns red upon a failing Build Type
- Project Configuration: The light turns red upon the failing of any build type within a project
- Server Configuration: The light turns red upon the failing of any build type within the server
In addition I have a request at this point to implement a branch configuration and I’ll get to that last.
TeamCity plugin implementation
All Configurations
All configuration types will require the following 3 common config items:
- [ServerRoot] (eg http://localhost:81 in my case)
- [Username]
- [Password]
All calls will be httpAuth based using the supplied username/password. I did have a request to allow windows based authentication but it’s problematic and my early adopters have agreed the above seems fair given all our calls are read only.
Build Type Configuration
Configure the plugin with a [BuildTypeId] config item and call the following…
http://localhost:81/httpAuth/app/rest/2017.1/builds?locator=buildType:[BuildTypeId],count:1
…and return the status of the build record returned (Broken|Ok).
Project Configuration
Configure the plugin with a [ProjectId] config item and call the following…
http://localhost:81/httpAuth/app/rest/2017.1/projects/id:[ProjectId]
…to gather the BuildTypeIds for that project.
Iterate over the BuildTypeIds calling the Build Type Configuration functionality and if any return a status of Broken is returned for the Project.
If there are child projects then iterate over those recursively doing the same until either a Broken status is returned or all recursion paths have been exhausted.
Server Configuration
Call the following…
http://localhost:81/httpAuth/app/rest/2017.1/projects
To return all ProjectId’s under the root node and iterate calling the Project Configuration functionality. If any return a status of Broken the plugin returns a status of broken.
The sticky ones…
I’ve recently had a request from an early adopter to supply an enhancement to the plugin that would allow the light to poll Build Type branches (ie builds resulting from setting the Branch filter on VCS triggers). This would give rise to two new plugin configurations…
Build Type Branch Configuration – Specified Branch
I think this one is easy. It’s essentially the Build Type Configuration functionality with a slightly modified API call (here I’ve supplied my exact call to return what I need in my current tests)…
Build Type Branch Configuration – Active Branches
The sticky bit comes when we consider active branches. I’ve been looking for a call along the lines of…
Without something like this there are a bunch of rules around whether the returned builds are active and it feels flaky, time consuming and perhaps impossible (unless I can get all the required parameters) re-implementing those my end.
If you take the time to get through all of that and respond.. thanks a million!
Tim
Please sign in to leave a comment.
Hi Tim,
Regarding your request to get the builds only from active branches, support is still experimental, but you would want to check this issue: https://youtrack.jetbrains.com/issue/TW-44148 (check out the last comments). While it won't work directly for builds, you can retrieve the set of active branches, then retrieve the builds for those branches.
For the rest, I didn't find it clear whether you are running a TeamCity plugin (that is, a plugin that runs in teamcity), or a plugin *for* teamcity but that runs in your own application. If it's the latter, then the REST calls seem ok, just note that you can add "fields=<field_name>" to only retrieve the fields you want instead of the full field. You can make requests to the server passing fields=* (or "fields=*(*)") to get th efull list of fields that an object returns, expanded if you add the "(*)" at the end. If it's the former, you should have access to a lot of that information directly without needing to make REST calls.
Hope this helps. If I didn't answer some of your questions, please feel free to ask, your post was long and I might have missed something.
Thanks Denis. That active branch call looks like it will do the trick. Did a bit of searching since this post which still didn't turn up anything so your reply's been a real help. The plugin does run inside our product and REST's been working fine.I'll use your fields qualifier to reduce the size but it's not a biggie as it's fast enough already as we only poll every few seconds at most.