How to integrate Teamcity and GitLab CI

I note down the step I did to integrate TeamCity build server and GitLab CI pipeline. I am using TeamCity 2017.1.15 and GitLab 10.0.3.

What you will get with this integration:

  • Small green tick for each commit showing that a build has run successfully on the commit
  • Bigger tick for each merge request (MR) showing that a build has run successfully on the head of the merge request
  • Ability to enforce a successful build before any MR can be merged

How to set up the integration

Tldr, you need to go through 3 main steps:

  1. Enable TeamCity integration in your GitLab project settings
  2. Enable TeamCity build configuration to monitor and trigger build for all (CI) branches
  3. Enable “Commit status publisher” build feature

You can continue below to get more details on the steps. Luckily, most the integration is already built-in, although not all works as expected.

  1. Enable TeamCity integration in your GitLab project settings
    1. Open Settings > Integration
    2. Fill in TeamCity URL (server URL), Build type (build configuration ID), username and password
    3. Tick Active and Trigger
  2. Enable TeamCity build configuration to monitor and trigger build for all (CI) branches
    1. Edit VCS Root, make sure Branch specification include +:refs/heads/(*) and +:/refs/(merge-requests/*)/head (don’t set it to +:*, which makes TeamCity confused about the branch name sent from GitLab)
    2. You don’t need to add any trigger in TeamCity, GitLab will automatically trigger a build for each push
  3. Enable Commit status publisher build feature
    1. Edit Build Configuration > Build Features, add Commit status publisher
    2. Choose VCS Root as All attached VCS Roots, choose Publisher as GitLab and fill in required GitLab information (you have to use an account with Developer permission in the GitLab project)

You have completed the setup. Right now if you push any change to GitLab repository, TeamCity will pick up the change, start the build and report the result back to GitLab.


  • Although GitLab has refs/merge_requests/#/head, you don’t need to monitor this branch in TeamCity. The branch of the MR can be built instead.
  • refs/merge_requests/#/head does not work for MR from fork. You will still see the MR in TeamCity, but the build result will not be recorded back in GitLab.
  • GitLab does not seem to have something like refs/merge_requests/#/merge just yet.



12 thoughts to “How to integrate Teamcity and GitLab CI”

  1. Hi,

    Interesting article, we have tried it and we can’t make it work for merge requests, we are using:
    “TeamCity 2017.2.3 (build 51047), effective release date 2017-11-27, currently running in the professional mode.
    Maximum number of authorized agents: 3 agents provided by professional edition license
    Maximum number of build configurations: 100 build configurations provided by professional edition license ”
    And gitLab as a hosted service.

    We don’t see the option mentioned for Git lab “Tick Active and Trigger”. Do we need to install git lab in our premises ?

    Any advice would be more than welcomed.

    1. In newer version of GitLab (both on and on premise), it seems that they removed the Trigger checkbox. You just need to tick Active as the screenshot below.

      The Trigger checkbox was also confusing to me. I am glad they removed it. Please let me know if you still have any difficulty.

  2. Thanks on the comment. As specified in the mentioned article, we needed to add this into the VCS root:

    “+:refs/heads/(*) and +:/refs/(merge-requests/*)/head”
    This actually gets the merge requests available as branches to be built from.

    Well we sorted out by creating a trigger with a slightly different format: “+:merge-requests/*”

    This triggers the build when a merge request.

    We haven’t been able to make the trigger from gitlab.

  3. I want two different teamcity builds get triggered by same gitlab repo. But it looks like it can only be one teamcity build at the same time.

    1. I believe you can do only step 2 for the second TeamCity server. TeamCity should still be able to watch for changes in the branch in trigger a build.
      However, I don’t think you will be able to setup any further integration than that.

  4. Hi,

    I am trying to integrate repo with sonarcloud . Can you please help me withe the changes required in maven/npm gitlab-ci.yaml file , also let me know if any config changes required in sonarcloud.

    Though this query is not relate to above post , appreciate your help on the same.

  5. Hi,
    How to trigger build in teamcity by adding a “Phrase” (eg: retrigger/recheck) as comment in Gitlab.
    Can you please help me what configurations we need to do both in Gitlab and Teamcity.

    Thank you.

  6. Thanks for the article.

    It seems, GitLab side with its TeamCity plugin is used only for Push events and not for Open merge request events – we would need a full support for GitLab webhooks in TeamCity to support all other kinds of GitLab events. So, not very useful at all, except for triggering refresh faster in cases when you have set it to a lower than 60 seconds value in TeamCity (but then you’ll miss merge request open events).

    Also, I’m not sure how to set TeamCity refspecs if I want a particular build configuration to monitor only merge-request branches and ignore master and other branches?
    I’ve tried to disable the automatic Trigger because I thought that it will be enough for GitLab to trigger the build and also I have unchecked the “Allow builds in the default branch” (as the help hint there also says I might want to disable this for pull requests), but then I got TeamCity error:

    Failed to start build #3 in branch feat_1 at 22 May 19 18:52 on Default Agent
    Failed to collect changes, error: Builds in default branch are disabled in build configuration
    The full log is

    [18:52:15][Collecting changes in 1 VCS root] VCS Root details
    [18:52:15][VCS Root details] “[email protected]#refs/heads/master” {instance id=1, parent internal id=2, parent id=BuildMergeRequests_GitmygiturlGitRefsHeadsM, description: “mygiturl.git#refs/heads/master”}

    I’m not sure why it even tries to collect changes in the default master branch at all instead of collecting the changes in merge-requests/5 branch?

    1. I have not tried to do a trigger only on opening of merge request. At the moment, we setup build for push trigger and the build result also get updated to all related merge requests.
      Have you tried to use branch specification +:/refs/(merge-requests/*)/head without turning off Allow builds in the default branch?

  7. Any updated instructions to use without doing magic steps on the gitlab side. Currently trying with TeamCity Pro 2021.2.3 and getting “not authorized” when pressing “Test Connection” ?

    I know this article is 4+ years old, but there are too few search results and the TeamCity documentation and UI is hopelessly vague on how to set things up, despite having dedicated menu options for connecting to gitlab CE/EE.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.