# TeamCity

## 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]://\**. * 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 * 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 * 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 * 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 * 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 * 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 ### 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.

* 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.

### 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 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 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%` * ```

``` 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` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/en/keeperpam/secrets-manager/integrations/teamcity.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.