Icon

You are viewing the documentation of TeamCity 8.x, which is not the most recently released version of TeamCity.
Go to the latest TeamCity documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

In this section:

Table of Contents

Integrate with an Issue Tracker

...

TeamCity Tray Notifier is used normally to watch builds and receive notifications from a single TeamCity server. However, if you have more than one TeamCity server and want to monitor them with Windows Tray Notifier simultaneously, you need to start a separate instance of Tray Notifier for each of the servers from the command line with the /allowMultiple option:

  • From the TeamCity Tray Notifier installation folder (by default, it's C:\Program Files\JetBrains\TeamCity run the following command:

    Code Block
    JetBrains.TrayNotifier.exe /allowMultiple

    Optionally, for each of the Tray Notifier instances you can explicitly specify the URL of the server to connect using the /server option. Otherwise, for each further tray notifier instance you will need to log out and change server's URL via UI.

    Code Block
    JetBrains.TrayNotifier.exe /allowMultiple /server:http://myTeamCityServer

...

If you need to move existing TeamCity installation to a new hardware or clean OS, it is recommended to follow instructions on copying the server from one machine to another and then switch from the old server to a new one. If you are sure you do not need to preserve old server, you can perform move operations instead of copying in those instructions.

...

Please also review the section for a list of directories that can be deleted without affecting builds consistency.

Wiki Markup
{hidden-data}

h3. Integrate with Wiki

You can use [external status widget|Configuring General Settings#addingStatusWidget] to incorporate information about a build status into any HTML page.

For example, to include the status widget into a Confluence page, ensure you have XXX plugin installed that will allow to include HTML snippets into any page and use markup like (do not forget to replace _<values>_:

{code}
{{include-html}}
<style type="text/css">
 @import" <TeamCity_server_URL>/css/status/externalStatus.css";
</style>
<script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1&buildTypeId=<buildConfigurationId1>&buildTypeId=<buildConfigurationId2>&buildTypeId=<buildConfigurationId3>">
</script>
{{include-html}}
{code}

TeamCity allows user to display information about current status of a build configuration on a Confluence Wiki page (as well as on any other web-page) [via the external status widget|Configuring General Settings#addingStatusWidget].

{note}Please beware that any information about build configuration published with the external status widget is available for *any* viewer of the page where you've integrated the widget.{note}

Please note that to integrate status widget into the Confluence page or another Wiki page you should have a macros or plugin which allows to insert plain HTML code into the page. For example, in Confluence you can use {{include-html}} macro.
{hidden-data}
Anchor
sharebuildnumber
sharebuildnumber

...

  1. Create build configuration C, then snapshot dependencies: A on C and B on C.
  2. Set the Build number format in A and B to:

    Code Block
    
    %dep.<btID>.system.build.number%
    

    Where <btID> is the ID of the build configuration C. The approach works best when builds reuse is turned off via the Do not run new build if there is a suitable one snapshot dependency option.

Read more about dependency properties.

...

Please also ensure that the distribution of the failover/backup server is of exactly the same version as the main server.

See also information on switching from one server to another.

...

At this time there is no dedicated feature to move projects or build configuration from one TeamCity server to another. Please plan your TeamCity deployment in advance with this in mind. Related supported ability is creating a copy of existing server.

Since TeamCity 8.0 it is possible to move settings of a project or a build configuration to another server with simple file copying. For earlier TeamCity versions see the comment.

...

If you use Cucumber for Java applications testing you should run cucumber with --expand and special --format options. More over you should specify RUBYLIB environment variable pointing on necessary TeamCity Rake Runner ruby scripts:

Code Block

<target name="features">
    <java classname="org.jruby.Main" fork="true" failonerror="true">
      <classpath>
        <pathelement path="${jruby.home}/lib/jruby.jar"/>
        <pathelement path="${jruby.home}/lib/ruby/gems/1.8/gems/jvyaml-0.0.1/lib/jvyamlb.jar"/>
        ....
      </classpath>
      <jvmarg value="-Xmx512m"/>
      <jvmarg value="-XX:+HeapDumpOnOutOfMemoryError"/>
      <jvmarg value="-ea"/>
      <jvmarg value="-Djruby.home=${jruby.home}"/>
      <arg value="-S"/>
      <arg value="cucumber"/>
      <arg value="--format"/>
      <arg value="Teamcity::Cucumber::Formatter"/>
      <arg value="--expand"/>
      <arg value="."/>
      <env key="RUBYLIB"
           value="${agent.home.dir}/plugins/rake-runner/rb/patch/common${path.separator}${agent.home.dir}/plugins/rake-runner/rb/patch/bdd"/>
      <env key="TEAMCITY_RAKE_RUNNER_MODE" value="buildserver"/>
    </java>
  </target>

...

Use URL like this:

Code Block
xml
xml

http://<your TeamCity server>/app/rest/buildTypes/id:<ID of build configuration>/builds/status:SUCCESS/number

...

  1. ensure the new server is configured to use another data directory and the database then the original server
    At this point you should be ready to run the copy TeamCity server.
  2. run new TeamCity server
  3. upon new server startup do not forget to update Server URL on Administration | Global Settings page. You will also probably need to disable Email and Jabber notifiers or change their settings to prevent new server from sending out notifications. If you use cloud integration, you might want to disable that as well.
  4. if you need the services on the copied server check that email, jabber and VCS servers are accessible from the new installation.
  5. install new agents (or select some form the existing ones) and configure them to connect to the new server (using new server URL)

See also the notes on moving the server from one machine to another.

...

It's advised to try new TeamCity version before upgrading your production server. Usual procedure is to create a copy of your production TeamCity installation, then upgrade it, try the things out and when everything is checked, drop the test server and upgrade the main one.
When you start the test server do not forget to disable Email and Jabber notifiers and change Server URL to the new one.

...

  1. Write a build script that will perform the deployment task for the binary files available on the disk. (e.g. use Ant or MSBuild for this. For FTP/SSH tasks check the Deployer plugin) You can also use Meta-Runner to reuse a script with convenient UI.
  2. Create a build configuration in TeamCity that will execute the build script and perform the actual deployment. If the deployment is to be visible or startable only by the limited set of users, place the build configuration in a separate TeamCity project and make sure the users have appropriate permissions in the project.
  3. In this build configuration configure artifact dependency on a build configuration that produces binaries that need to be deployed.
  4. Configure one of the available triggers in the deploying build configuration if you need the deployment to be triggered automatically (e.g. to deploy last successful of last pinned build), or use "Promote" action in the build that produced the binaries to be deployed.
  5. Consider using snapshot dependencies in addition to artifact ones and check Build Chains tab to get the overview of the builds.
  6. If you need to parametrize the deployment (e.g. specify different target machines in different runs), pass parameters to the build script using custom build run dialog. Consider using Typed Parameters to make the custom run dialog easier to use or handle passwords.
  7. If the deploying build is triggered manually consider also adding commands in the build script to pin and tag the build being deployed (via sending a REST API request).
    You can also use a build number from the build that generated the artifact.

...

Related section on the official site: Continuous Deployment with TeamCity

Wiki Markup
{hidden-data}
related blog posts:
http://java.dzone.com/articles/automated-deployments-teamcity
http://blog.anthonybaker.me/2013/05/how-to-automate-app-deployment-in_1352.html
http://www.troyhunt.com/2010/11/you-deploying-it-wrong-teamcity_25.html
{hidden-data}

...

If the tool reports code-attributing information like Inspections or Duplicates, TeamCity-bundled report can be used to display the results. A custom plugin will be necessary to process the tool-specific report into TeamCity-specific data model. Example of this can be found in XML Test Reporting plugin and FXCop plugin (see a link on Open-source Bundled Plugins).

See also #Import coverage results in TeamCity.

For advanced integration, a custom plugin will be necessary to store and present the data as required. See Developing TeamCity Plugins for more information on plugin development.

...

  • man-in-the middle concerns
    • between TeamCity server and user's web browser: It is advised to use HTTPS for the TeamCity server. During login, TeamCity transmits user login password in an encrypted form with moderate encryption level.
    • between TeamCity agent and TeamCity server: see the section.
    • between TeamCity server and other external servers (version control, issue tracker, etc.): the general rules apply as for a client (TeamCity server in the case) connecting to the external server, see guidelines for the server in question.
  • user that has access to TeamCity web UI: the specific information accessible to the user is defined via TeamCity user roles.
  • users who can change code that is used in the builds run by TeamCity: the users have the same permissions as the system user under which TeamCity agent is running. Can access and change source code of other projects built on the same agent, modify TeamCity agent code, publish any files as artifacts for the builds built on the agent (which means the files can be then displayed in TeamCity web UI and expose web vulnerabilities or can be used in other builds), etc. It is advised to run TeamCity agents under users with only necessary set of permissions and use agent pools feature to insure that projects requiring different set of access are not built on the same agents. Such users can also view all the projects on the server, see details in the corresponding issue TW-24904.

    Wiki Markup
    {hidden-data}Prior to TeamCity 7.1 there was a security issue which allowed to get system administrator permissions: see [TW-21413|http://youtrack.jetbrains.com/issue/TW-21413]){hidden-data}

  • users with System Administrator TeamCity role: It is assumed that the users also have access to the computer on which TeamCity server is running under the user account used to run the server process. Thus, some operations like server file system browsing can be accessible by the users.
  • TeamCity server computer administrators: have full access to TeamCity stored data and can affect TeamCity executed processes. Passwords that are necessary to authenticate in external systems (like VCS, issue trackers, etc.) are stored scrambled under TeamCity Data Directory and can also be stored in the database. However, the values are only scrambled, which means they can be retrieved by the users who have access to the server file system or database.
  • TeamCity agent computer administrators: same as "users who can change code that is used in the builds run by TeamCity".
  • Other:
    • TeamCity web application vulnerabilities: TeamCity development team makes reasonable effort to fix any significant vulnerabilities (like cross-site scripting possibilities) once they are uncovered. Please note that any user that can affect build files ("users who can change code that is used in the builds run by TeamCity" or "TeamCity agent computer administrators") can make a malicious file available as build artifact that will then exploit cross-site scripting vulnerability. (TW-27206)
    • TeamCity agent is fully controlled by the TeamCity server: since TeamCity agents support automatic updates download from the server, agents should only connect to a trusted server. An administrator of the server computer can force execution of arbitrary code on a connected agent.

...

Please note that TeamCity preserves builds history and other data stored in the database for deleted projects/build configurations for 24 hours since the deletion time. All the associated data (builds and test history, changes, etc.) is removed during the next cleanup after 24 hours timeout elapses.

The config/_trash directory is not cleaned automatically and can be emptied manually if you are sure you do not need the deleted projects. No server restart is required.

Anchor
proxySetup
proxySetup

...

  1. An internal TeamCity server should work under the same context as it is visible from outside by an external address. To change TeamCity context root from / to /tc: stop TeamCity server; move <TeamCity home>\webapps\ROOT directory to <TeamCity home>\webapps\tc; start TeamCity server. Now TeamCity is available via http://teamcity.local:8111/tc/.
  2. Set up reverse proxy. The settings below ensure requests to http://teamcity.public:400/tc are redirected to http://teamcity.local:8111/tc and the redirect URLs sent back to the clients are correctly mapped by the proxy server:
    • for Apache

       

      No Format
      
      LoadModule  proxy_module         /usr/lib/apache2/modules/mod_proxy.so
      LoadModule  proxy_http_module    /usr/lib/apache2/modules/mod_proxy_http.so
      LoadModule  headers_module       /usr/lib/apache2/modules/mod_headers.so
      
      ProxyRequests       Off
      ProxyPass           /tc http://teamcity.local:8111/tc connectiontimeout=240 timeout=1200
      ProxyPassReverse    /tc http://teamcity.local:8111/tc
      
    • for Nginx

       

      No Format
           server {
              listen       400;
              server_name  teamcity.public;
      
              location /tc {
                  proxy_pass        http://teamcity.local:8111/tc;
                  proxy_set_header  X-Forwarded-For $remote_addr;
                  proxy_set_header  Host $server_name:$server_port;
              }
          }
      

       

      Some other Nginx settings must be changed as well:

       

      No Format
      
      http {
          proxy_read_timeout     1200;
          proxy_connect_timeout  240;
          client_max_body_size   0;
          ....
      }
      

       

      Where client_max_body_size controls the maximum size of an HTTP request. It is set to 0 to allow uploading big artifacts to TeamCity.
  3. The TeamCity server must know the original remote address of the client. This is especially important for agents, because the server tries to establish connection with an agent to check whether the agent is behind a firewall or not. For this you need to add the following into the Tomcat main <Host> node of the conf\server.xml file (see also doc):

    Code Block
    xml
    xml
    
    <Valve
       className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="x-forwarded-for"
       protocolHeader="x-forwarded-proto"
       internalProxies="192\.168\.0\.1"
       />
    

    Where internalProxies must be replaced with the IP address of Nginx or Apache proxy server.

    Wiki Markup
    {hidden-data}see also comment: [http://youtrack.jetbrains.com/issue/TW-11166#comment=27-331468]{hidden-data}
    Wiki Markup
    {hidden-data}
    some more Nginx params which might also relate:
    
       client_header_timeout  10m;
       client_body_timeout    10m;
       send_timeout           10m;
       proxy_max_temp_file_size 10240m;
    {hidden-data}

If you need to use different protocols for the public and local address (e.g. make TeamCity visible to the outside world as https://teamcity.public:400) or your proxy server does not support redirect URL rewriting, please use the following approach. Setup a proxying server to redirect all requests to teamcity.public:400 to a dedicated port on a TeamCity server (8111 in the example below) and edit <TeamCity home>\conf\server.xml to change the existing or add a new Connector node:

Code Block
xml
xml

<Connector port="8111" protocol="HTTP/1.1"
               maxThreads="200" connectionTimeout="60000"
               redirectPort="400"  useBodyEncodingForURI="true"
               proxyName="teamcity.public"
               proxyPort="400"
               secure="false"
               scheme="http"
               />

...

Make sure you're using InnoDB database engine for tables in TeamCity database. You can check what engine is used with help of this command:

Code Block
sql
sql

show table status like '<table name>';

or for all tables at once:

Code Block
sql
sql

show table status like '%';

...

Too small value in innodb_buffer_pool_size can affect performance significantly:

Code Block

# InnoDB, unlike MyISAM, uses a buffer pool to cache both indexes and
# row data. The bigger you set this the less disk I/O is needed to
# access data in tables. On a dedicated database server you may set this
# parameter up to 80% of the machine physical memory size. Do not set it
# too large, though, because competition of the physical memory may
# cause paging in the operating system.  Note that on 32bit systems you
# might be limited to 2-3.5G of user level memory per process, so do not
# set it too high.
innodb_buffer_pool_size=2000M

...

If the default MySQL binary logging format is not MIXED (it depends on the version of MySQL you are using), then it should be explicitly set to MIXED:

Code Block

binlog-format=mixed 

Import coverage results in TeamCity

...

  • publish coverage HTML report as TeamCity artifact: most of the tools produce coverage report in HTML format, you can publish it as artifact and configure report tab to show it in TeamCity. If published artifact name is coverage.zip and there is index.html file in it, report tab will be shown automatically. As to running an external tool, check #Integrate with Build and Reporting Tools.
  • extract coverage statistics from coverage report and publish statistics values to TeamCity with help of service message: if you do so, you'll see coverage chart on build configuration Statistics tab and also you'll be able to fail a build with the help of a build failure condition on a metric change (for example, you can fail build if the coverage drops).

...

  1. Go to the Agents page in the TeamCity Web UI and select the agent.
  2. Disable the agent to temporarily remove it from the build grid. Add a comment (optional). To enable the agent automatically after a certain time period, check the corresponding box and specify the time.
  3. Select the build to debug.
  4. Open the Custom Run dialog and specify the following options:
    1. In the Agent drop-down, select the disabled agent.
    2. It is recommended to select the run as personal build Personal Build option to avoid intersection with regular builds.
  5. When debugging is complete, enable the agent manually if automatic re-enabling has not been configured.

...