# TeamCity

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FkN1xTeS7z68jeRshgStj%2Fkeeper%20and%20Team%20City.jpg?alt=media&#x26;token=41e1f272-9736-495e-9f51-7b76baaf6850" alt=""><figcaption></figcaption></figure>

## About

TeamCity is a general-purpose CI/CD software platform that allows for flexible workflows, collaboration and development practices. A solution that will allow for successful continuous integration, continuous delivery, and continuous deployment within your DevOps process.

The plugin allows TeamCity servers *(version 2018.1 or newer)* to integrate with Keeper Secrets Manager to make managing secrets in TeamCity easier and more secure.

## Features

* Use secrets from the Keeper vault in TeamCity builds
* Keeper Secrets Manager plugin installs as a TeamCity **Connection**

## Prerequisites

* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details)
  * Secrets Manager add-on enabled for your Keeper subscription
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application
* An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration)
  * The TeamCity plugin accepts Base 64 format configurations

## Installation

### Installing Plugin from JetBrains Plugins Repository

* Go to **Administration | Plugins** in TeamCity and click Browse plugins repository.
* Find the **Keeper Secrets Manager** plugin, click **Get**, and then **Install to http\[s]://\<teamcityUrl>**.
* Confirm the plugin installation by clicking **Install**.
* To enable the plugin after installation, click the plugin context menu and select **Load**.

### Installing Plugin via Web UI <a href="#installingpluginviawebui" id="installingpluginviawebui"></a>

* Download the latest version of TeamCity KSM plugin ZIP file from [here](https://github.com/Keeper-Security/secrets-manager-teamcity/releases/latest).
* Go to the **Administration | Plugins** page and upload the plugin ZIP archive from your local machine using the corresponding link.

### Installing Plugin Manually <a href="#installingpluginmanually" id="installingpluginmanually"></a>

* Copy the ZIP plugin package into the`<`[`TeamCity Data Directory`](https://www.jetbrains.com/help/teamcity/teamcity-data-directory.html)`>/plugins` directory. If you have an earlier version of the plugin in the directory *(though the plugin package can be named differently)*, remove it.

### Enabling Plugin <a href="#enablingplugin" id="enablingplugin"></a>

* To enable the plugin after installation, click the plugin context menu and select **Load**. The plugin will be enabled without the server restart.

### Uninstalling Plugin via Web UI <a href="#uninstallingpluginviawebui" id="uninstallingpluginviawebui"></a>

* Go to **Administration | Plugins**, locate an external plugin in the list, click the arrow icon next to it, and select **Delete**.
* Once the plugin is deleted, the option to restart the server appears on the page. Click it and check that the plugin version is no longer listed in **Administration | Plugins**.

### Uninstalling Plugin Manually <a href="#uninstallingpluginmanually" id="uninstallingpluginmanually"></a>

* Remove the plugin package from the `<`[`TeamCity Data Directory`](https://www.jetbrains.com/help/teamcity/teamcity-data-directory.html)`>/plugins` directory and restart the TeamCity server.

## Setup <a href="#configuring-discovery-credentials" id="configuring-discovery-credentials"></a>

### Configuring Connections

When created, a connection can be used in all the nested subprojects of the current project. If you add a connection in the Root project, it will become available on the whole server.

To add a connection, go the target project's settings, open the **Connections** page, and click **Add Connection**. Select the connection type **Keeper Vault**, set its **Display name** to distinguish it from the others, and configure it as described below.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FNdlO2intZScfxPHoCFPk%2Fteamcity-ksm-connections.png?alt=media&#x26;token=1c3b7d62-6b15-41d7-a102-4c770ffec558" alt=""><figcaption><p>Adding connection of type Keeper Vault</p></figcaption></figure>

* In **Project Administration | Connections**, click **Add Connection**.
* Select **Keeper Vault** as the connection type.
* Specify the token - paste a valid KSM config *(see* [*Prerequisites*](#prerequisites)*)*.
* Save the connection.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FvtxIhGbV9B62dtsOIIhO%2Fteamcity-ksm-connections-add.png?alt=media&#x26;token=f7d6600e-d4de-4e4b-91d7-25381bc18ce6" alt=""><figcaption><p>Configure Keeper Vault Connection</p></figcaption></figure>

### Using secrets in TeamCity builds

To consume Keeper vault secrets from your TeamCity server, you will need to:

* Create a secret in Keeper vault and share it to the corresponding KSM Application
* Configure a TeamCity parameter that resolves the secret using [Secrets Manager Notation URIs](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation)

### Using Build Parameters in Build Configuration Settings <a href="#usingbuildparametersinbuildconfigurationsettings" id="usingbuildparametersinbuildconfigurationsettings"></a>

In most build configuration settings, you can use a reference to a build parameter instead of using the actual plain-text value. Before starting a build, TeamCity resolves all references with the available parameters. If there are references that cannot be resolved, they are left as is, and a respective warning appears in the build log. To reference a build parameter, use its name enclosed in percentage characters: for example, `%env.KsmSecret1%`.

**Parameters** tab allows adding, editing, and deleting new parameters/properties/variables, or redefining their predefined values.

{% hint style="warning" %}
Any text enclosed in percentage characters will be interpreted by TeamCity as a reference to a parameter. If the parameter cannot be found in the build configuration, this reference becomes an *implicit agent requirement* and such build configuration can only be run on an agent with this parameter defined. The agent-defined value will be used in the build.\
\
If you want to prevent TeamCity from treating the text in the percentage characters as a reference to a parameter, use two percentage characters. Every occurrence of `%%` in the values where parameter references are supported will be replaced with `%` before passing the value to the build. For example, if you want to pass `%Y%m%d%H%M%S` into the build, change it to `%%Y%%m%%d%%H%%M%%S`.
{% endhint %}

### Example Workflow <a href="#exampleworkflow" id="exampleworkflow"></a>

Define a build parameter on a build configuration level and use it in a build step.

1. Go to **Build Configuration Settings | Parameters**.
2. Click **Add new parameter**.
3. Enter the parameter's name and value. Change parameter's **Kind** to *Environment variable (env.)*.

   * Name: `username`
   * Value: `%keeper://UserRecord1/fields/login%`
   *

   ```
   <figure><img src="../../.gitbook/assets/teamcity-ksm-parameter.png" alt=""><figcaption><p>Adding New Parameter</p></figcaption></figure>
   ```
4. Save the parameter.
5. Go to **Build Steps**.
6. Click **Add build step**.
7. Choose the [Command Line](https://www.jetbrains.com/help/teamcity/command-line.html) runner type.
8. In the **Custom script** field, enter the following command:\
   `echo UserName %env.username%`

   For a build, this command will be resolved as follows *(note that actual value is masked in logs but used in actual commands):*

   ```
   echo UserName *****
   ```
9. Save the build step and run a new build.

{% hint style="warning" %}
The plugin accepts both Keeper Notation prefix `keeper://NotationURI` and TeamCity style prefix `keeper:NotationURI` in build parameters, environment variables etc. *Check the examples below.*
{% endhint %}

**Parameter Examples:**

* Environment variable `env.User` - `keeper:abcdABCDabcdABCDuvwxyz/field/login`
* Environment variable `env.Secret` - `keeper://MyRecord1/custom_field/Secret1`