How to trigger a TeamCity build on Git commit

In this page

Overview

TeamCity is a build management and continuous integration server from JetBrains (the makers of IntelliJ IDEA and ReSharper).

Watch this short tutorial video about configuring TeamCity automations, then follow the step-by-step guides in the next sections:

Starting a TeamCity build after every changeset

This automation starts a TeamCity build when a new changeset is received.

It is the simplest way to integrate TeamCity to your DevOps pipeline. It starts the build once per changeset, after all the commits in the changeset are already in the repository.

Configuration

1. Login to TeamCity as admin, go to your profile → My Settings & Tools → Access Tokens. If your TeamCity version does not support Access Tokens, continue with step 4.
2. Click Create access token.
3. Enter a token name in the Token name field. Copy the generated token, because it cannot be recovered in the future. Click Close.
4. Login to Jira as admin, go to Administration → System → Automation rules.
5. Click Create rule.
6. Select the trigger Changeset accepted (from the DevOps category).
7. Click Save.
8. Click New action.
9. Select the action Send web request.
   1. If you are using an older TeamCity version which does not support CSRF protection (or it's disabled), skip these steps and continue with step 12.
   2. Enter the Webhook URL as:

      <YOUR_TEAMCITY_SERVER_BASE_URL>/authenticationTest.html?csrf

      Replace the placeholder with your actual TeamCity base URL.
   3. Add a header with the name "Authorization" and with the value of "Bearer <YOUR_TEAMCITY_ACCESS_TOKEN>". Replace the placeholder with the actual Access Token created at step 2.
   4. Choose GET as HTTP method.
   5. Choose Empty as Webhook body.
   6. Check the Delay execution of subsequent rule actions until we've received a response for this webhook checkbox.
   7. Validate your settings in the Validate your webhook configuration section below.
      Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
10. Click Save.
11. Click New action.
12. Select the action Send web request.
    1. Enter the Webhook URL as:

       <YOUR_TEAMCITY_SERVER_BASE_URL>/app/rest/latest/buildQueue

       Replace the placeholder with your actual TeamCity base URL.
    2. Add a header with the name "Authorization" and with the value of "Bearer <YOUR_TEAMCITY_ACCESS_TOKEN>". Replace the placeholder with the actual Access Token created in step 2.
       (If your TeamCity version does not support Access Tokens, use basic authentication instead: Add a header with the name "Authorization" and with the value of Basic <CREDENTIALS> where credentials is the Base64 encoding of your TeamCity username and password joined by a single colon :.)
    3. If you executed step 9, add a header with the name "X-TC-CSRF-Token" and with the value of {{webhookResponse.body}}.
       (For older TeamCity versions, add a header with the name "Origin" and with the value of your TeamCity base URL.)
    4. Add a header with the name "Content-Type" and with the value "application/xml".
    5. Choose POST as HTTP method.
    6. Choose Custom data as Webhook body.
    7. Enter the following data:

       <build>
       	<buildType id="BUILD_CONFIGURATION_ID"/>
       </build>
       

       Replace the actual value of your build configuration ID, located at your build settings in TeamCity.
    8. Validate your settings in the Validate your webhook configuration section below. It will start a build if the configuration is valid.
       Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
13. Click Save.
14. Name your automation rule intuitively, and click Turn it on.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug.

2. The TeamCity build will be started.

Troubleshooting

If you don't get the expected results:

1. See the general troubleshooting steps.

Starting a TeamCity build with a specific command

This automation starts a TeamCity build when the changeset includes a commit with a commit message that contains a certain command.

It is a more flexible variant of the previous automation, because you can control whether to start the build or not.

Configuration

1. Login to TeamCity as admin, go to your profile → My Settings & Tools → Access Tokens. If your TeamCity version does not support Access Tokens, continue with step 4.
2. Click Create access token.
3. Enter a token name in the Token name field. Copy the generated token, because it cannot be recovered in the future. Click Close.
4. Login to Jira as admin, go to Administration → System → Automation rules.
5. Click Create rule.
6. Select the trigger Genius Commit created (from the DevOps category).
7. Choose the command Build, and click Save.
8. Click New action.
9. Select the action Send web request.
   1. If you are using an older TeamCity version which does not support CSRF protection (or it's disabled), skip these steps and continue with step 12.
   2. Enter the Webhook URL as:

      <YOUR_TEAMCITY_SERVER_BASE_URL>/authenticationTest.html?csrf

      Replace the placeholder with your actual TeamCity base URL.
   3. Add a header with the name "Authorization" and with the value of "Bearer <YOUR_TEAMCITY_ACCESS_TOKEN>". Replace the placeholder with the actual Access Token created at step 2.
   4. Choose GET as HTTP method.
   5. Choose Empty as Webhook body.
   6. Check the Delay execution of subsequent rule actions until we've received a response for this webhook checkbox.
   7. Validate your settings in the Validate your webhook configuration section below.
      Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
10. Click Save.
11. Click New action.
12. Select the action Send web request.
    1. Enter the Webhook URL as:

       <YOUR_TEAMCITY_SERVER_BASE_URL>/app/rest/latest/buildQueue

       Replace the placeholder with your actual TeamCity base URL.
    2. Add a header with the name "Authorization" and with the value of "Bearer <YOUR_TEAMCITY_ACCESS_TOKEN>". Replace the placeholder with the actual Access Token created in step 2.
       (If your TeamCity version does not support Access Tokens, use basic authentication instead: Add a header with the name "Authorization" and with the value of Basic <CREDENTIALS> where credentials is the Base64 encoding of your TeamCity username and password joined by a single colon :.)
    3. If you executed step 9, add a header with the name "X-TC-CSRF-Token" and with the value of {{webhookResponse.body}}.
       (For older TeamCity versions, add a header with the name "Origin" and with the value of your TeamCity base URL.)
    4. Add a header with the name "Content-Type" and with the value "application/xml".
    5. Choose POST as HTTP method.
    6. Choose Custom data as Webhook body.
    7. Enter the following data:

       <build>
       	<buildType id="BUILD_CONFIGURATION_ID"/>
       </build>
       

       Replace the actual value of your build configuration ID, located at your build settings in TeamCity.
    8. Validate your settings in the Validate your webhook configuration section below. It will start a build if the configuration is valid.
       Tip: if the URL contains smart values (variables), replace those with actual values (constants) for the time of the validation, then revert to the smart values after the configuration was successfully validated.
13. Click Save.
14. Name your automation rule intuitively, and click Turn it on.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build

2. The TeamCity build will be started.

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command was included in the commit message?
3. See the general troubleshooting steps.

Starting a TeamCity build with a specific command and build configuration ID

This automation starts a TeamCity build by parsing the build configuration ID from the VCS commit message:

It is a more flexible variant of the previous automation that allows choosing the build configuration.

Configuration

In this example, the parameter "buildConfigId" will be parsed from the commit message and passed to the build.

For this, first implement the "parameterless" automation using the previous guide. Then, execute these additional steps for the parameter:

1. Login to Jira as admin, go to Commits → Genius Commands.
2. Edit the command named Build.
3. Enter the following regular expression as a parameter pattern: (?<buildConfigId>.*).
4. Click Save.
5. Navigate to Administration → System → Automation rules.
6. Select your rule and edit the Send web request action.
7. Modify the Custom data as:

   <build>
       <buildType id="{{devops.buildConfigId.xmlEncode}}"/>
   </build>
   

   Note that the command parameters should be XML-encoded with .xmlEncode. Learn more about customizing the request in the TeamCity REST API documentation.
8. Click Save, then Publish changes.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build LRT

2. The TeamCity build configuration with the ID "LRT" will be started.

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command followed by the parameter was included in the commit message?
3. See the general troubleshooting steps.

Starting a TeamCity build with a specific command and build configuration parameter

This automation starts a TeamCity build by parsing the build configuration ID from the VCS commit message:

It is a more flexible variant of the previous automation that allows passing a build configuration parameter.

Configuration

In this example, the parameter "buildConfigParameter" will be parsed from the commit message and passed to the build.

For this, first implement the "parameterless" automation using the previous guide. Then, execute these additional steps for the parameter:

1. Login to TeamCity as admin, go to your build configuration → Edit Configuration Settings → Parameters.
2. Click Add new parameter.
3. Enter "profile" in the Name field and set a default value if need (e.g. "production") in the Value field.
4. Click Save.
5. Login to Jira as admin, go to Commits → Genius Commands.
6. Edit the command named Build.
7. Enter the following regular expression as a parameter pattern: (?<buildConfigParameter>.*).
8. Click Save.
9. Navigate to Administration → System → Automation rules.
10. Select your rule and edit the Send web request action.
11. Modify the Custom data as:

    <build>
        <buildType id="BUILD_CONFIGURATION_ID"/>
        <properties>
            <property name="profile" value="{{devops.buildConfigParameter.xmlEncode}}"/>
        </properties>
    </build>
    

    Note that the command parameters should be XML-encoded with .xmlEncode. Learn more about customizing the request in the TeamCity REST API documentation.
12. Click Save, then Publish changes.

Usage

1. Create a commit with this commit message:

   Fix the FOO-1 bug. @build production

2. The TeamCity build will be started with the "profile" parameter set to "production".

Troubleshooting

If you don't get the expected results:

1. Check if the @build command is defined in the Genius Commands screen? (It's a default command.)
2. Check if the @build command followed by the parameter was included in the commit message?
3. See the general troubleshooting steps.

Questions?

Ask us any time.