A TeamCity plugin that shows a high level view of what builds have been deployed into what environments across multiple projects.
Once enabled, a new "Deployments" project tab will appear on deployment builds showing the dashboard content, and all sub-projects.
A deployment build in TeamCity can be selected from the build configuration's "General" tab. This changes a build's "Run" button to "Deploy" and lists it on the build overview.
TeamCity does not have (or probably need), the notion of a deployment environment. However, the dashboard needs to be able to correlate build configurations (and the deployment builds that are created) with an environment so it can be placed in the relevant part of the dashboard.
The deployment dashboard classifies a build deployments as part of a particular environment, either by a build variable1 or by the name of the build configuration (though the latter is arguably less useful being more likely to be an action such as "Deploy Dev").
Enabling the plugin in the configuration will show three settings.
Projects inherit parent configuration unless overridden at a lower level. If all projects in a TeamCity instance are the same, the configuration only needs to be set in the root project.
Here are some ideas to help support different build configurations.
Environments Separated by the TeamCity Build Chain
A natural way to set up TeamCity is to split deployments into environments by using separate build configurations and link them using snapshot dependencies so that they can be represented on a pipeline (or 'build chain' in TeamCity parlance). Build variables1 can be set on each deployment stage to indicate the environment to the dashboard.
Single Build Configuration that can be Deployed to Multiple Environments
The environment to deploy to is determined by more than just the build configuration. Perhaps the environment is determined by the agent, or the user is prompted at deploy time.
When using a single build configuration, the Multi-Environment Build Configurations
option
should be enabled in order to more deeply search the build history as by default the plugin
only fetches the last deployment for a build configuration for efficiency reasons.
Composite Environment Information
Some environments consist of multiple deployment locations, such as deploying to different cloud
regions. One way of visualising such multi-region deployments is to define a new composite
parameter that combines environment and region. For example, DEV and PRD in region EUR and USA
could be done by defining a parameter with a value like %environment%-%region%
. Once the plugin
has been configured to use this new parameter as the environment key, the environment list of
deploys to show would then be DEV-EUR,DEV-USA,DEV-EUR,PRD-USA
.
Custom Deployment Information
Sometimes it is useful to display other information with each deployment, such as the branch
used to build. The Custom Property feature can be used to for this, e.g. setting it to
teamcity.build.branch
.
Multiple pieces of information can be displayed as the custom information by creating a new property that concatenates different pieces of information and referencing that property. Dynamic information constructed programmatically in the build steps can also be provided by using TeamCity service messages.
If the information is too long for the field it will be truncated, but the full information can be displayed by hovering over it.
The dashboard shows deployments for the current project and all sub-projects. This allows the greatest visibility at the higher levels. However, it can be hard to find consistency of environment names between multiple teams and what properties in TeamCity they use to classify them.
There are two ways to handle this:
By default, the dashboard will show the TeamCity build number as the version. This can be
customised using TeamCity Service Messages.
Alternatively a property can be used that references the original build in a TeamCity build
chain, for example a VERSION
property set to %dep.Project_Build.version%+%dep.Project_Build.build.counter%
.
This actual value be any formatted version string, but in order to visualise the journey of the build through environments the dashboard interprets the version number to work out which is the latest build and de-emphasises any deployments that are not. This is why in the screenshot above the older builds are slightly faded, to keep emphasis on a new build moving towards production.
The format supported is standard SemVer 2. For example 1.2.3
or 1.2.3+45
if a build number is required.
If the TeamCity build number is being used for other purposes, or it contains other information,
the Version Property
in the plugin configuration can be used for plugin use instead.
Builds in TeamCity will be performed for many reasons and not all of them will be relevant to show on the dashboard. This plugin will only show builds if the following are true:
Deployment
and therefore has a 'Deploy' button rather
than 'Run'
Multi-Environment Build Configuration
is set, the plugin gives up trying to find
a deployment for a configured environment after 1000 entries in the history.This project is written in JavaScript with React for the frontend, and Kotlin for the backend. The backend manages configuration, queries the build data, and provides a REST endpoint to provide the React frontend with the required deployment and configuration data.
The easiest way to build the project is to:
build.sh
from the root directory (only Docker required)deployment-dashboard.zip
file to <TeamCityData>/plugins/
If there is an error running build.sh
such as Cannot autolaunch D-Bus without X11 $DISPLAY
remove DOCKER_BUILDKIT=1
from this script the first time it's run.
While this method is fairly simple, it's quite slow even after the first run because Gradle has a very cold start when run from a Docker image, and has to download dependencies on every build. PRs to force Gradle to make better use the Docker cache very welcome!
A much quicker build cycle is to install NPM and Gradle locally, and do the equivalent of the Dockerfile instructions on the host. This makes builds run in seconds rather than minutes.
1: Build variables are defined using the normal TeamCity convention for addressing build variables, and can be a configuration parameter (no prefix), environment variable (prefix of 'env.') or system property with prefix of 'system.'.