TeamCity Cloud
 
2022.12
Get TeamCity Cloud
You are viewing the documentation for an earlier version of TeamCity Cloud.
  1. CI Tutorials
  2. How to Configure CI/CD for JetBrains Space

How to Configure CI/CD for JetBrains Space

Edit page Last modified: 24 November 2022

JetBrains Space is a full-cycle collaboration solution for software development teams. This guide explains how to achieve continuous integration and delivery of JetBrains Space projects by integrating them with TeamCity.

Integration with TeamCity brings the following advantages to the JetBrains Space users:

  • Compiling, testing, and deploying projects within the same environment.

  • Building source code of merge requests and merging them automatically after a successful build.

  • Extensive build overview: diffs and artifacts, detailed test reports on the fly, code coverage, inspections, and various other metrics. Statuses of builds and code reviews are cross-shared between systems for easier monitoring.

  • Flexible pipelines where builds depend on one another and share settings and results.

  • Ability to configure builds as code, in Kotlin DSL.

  • Authentication with a single account in both systems: VCS (JetBrains Space) and CI/CD (TeamCity).

This guide consists of the common preliminary setup and optional procedures for enabling each component of the integration.

Prerequisites

To perform all the steps described in this guide, you need to have:

  • Project administration rights in the JetBrains Space instance of your organization.

  • Project administration rights in either the TeamCity Cloud instance or TeamCity On-Premises server of your organization.

  • To enable authentication via JetBrains Space in TeamCity, system administration rights in TeamCity.

Preliminary Setup

Connecting TeamCity to JetBrains Space involves two steps: (1) creating a service application for TeamCity authentication in your Space instance and (2) creating a preset of connection to Space.

Step 1: Create Application in JetBrains Space

In your JetBrains Space instance:

  1. On the navigation bar, click Extensions and choose Installed to organization.

  2. Click New application.

  3. Enter a convenient name (for example, Space-to-TeamCity), save the application, and click Go to application settings.

  4. Configure In-context Authorization:

    1. On the Authorization tab, click Authorize in new context.

    2. Enter the name of the Space project you are about to access from TeamCity and click Authorize.

    tip

    When you create a project in JetBrains Space, it does not automatically add you to this project as a member — this needs to be done manually. TeamCity will be able to see only those projects where you are listed as a member.

    1. (Optional) If you want TeamCity to be able to publish commit statuses to Space, you will need to add a respective permission.
      Click Configure and enable Git Repositories | Report external check status. This request has to be accepted by the project administrator.

  5. Configure Global Authorization:

    1. On the Authorization tab, click Configure.

    2. To establish general access from TeamCity to Space, enable the Members | View member profile permission and click Save. This request has to be accepted by the server administrator.

  6. Configure Authentication Mode:

    1. Go back to the app's Overview and open the Authentication tab.

    2. Enable Client Credentials Flow.

    3. To be able to use authentication via Space in TeamCity or/and to create projects/configurations from Space repositories, enable Authorization Code Flow as well. Enter the redirect URI (https://<server>:<port>/oauth/space/accessToken.html) of your TeamCity Server.

    4. Copy the app's Client ID and Client secret. You will need them for configuration on the TeamCity side.

Now, you can return to TeamCity and add a connection to JetBrains Space.

Step 2: Establish Connection to JetBrains Space

tip

TeamCity allows you to configure all settings of your connection to a service in one place and then reuse these settings in different projects and build configurations. If you add such a connection on the Root project level, this will allow using its settings to connect any other project on the server. To make a connection available only in a certain project, you need to add it in this project.

To create a connection to your JetBrains Space instance:

  1. Go to Project Settings | Connections and click Add Сonnection.

  2. Choose the JetBrains Space connection type.

    Create a connection to Space

  3. Enter the settings as follows:

    • Space URL: the URL of your Space instance (<company_name>.jetbrains.space).

    • Client ID: the client ID value copied from the Space app's Authentication tab.

    • Client secret: the client secret value copied from the Space app's Authentication tab.

  4. Save the connection.

At this stage, you are free to access your JetBrains Space instance from the current project or any of its subprojects whenever necessary.

Connecting TeamCity Projects with JetBrains Space Projects

There are three ways to integrate a VCS repository with TeamCity:

  • Create a TeamCity project based on a repository.

  • Create a build configuration based on a repository in an existing TeamCity project.

  • Create a VCS root based on a repository in an existing TeamCity project.

We will describe the first approach as it's the most popular and self-sufficient. However, you can always add one more Space root or build configuration to an existing project — the procedure is similar.

Let's create a subproject of the project where you added the Space connection during the preliminary setup. If it is the Root project, go to Administration | Projects and click Create project there.

You will notice the new button: From JetBrains Space. Its name depends on the Display name you gave to the connection, but you can always distinguish Space connections from others by the Space logo. To create a new project:

  1. Click From JetBrains Space.

  2. As it is the first time you connect this server to your Space instance, you have to authenticate in Space via your user profile. Click Sign in to Space and accept the access request. Next time, you won't have to confirm it again, unless you sign out or change your password.

    Create a project from a Space repository

    tip

    If you get the OAuth 2.0 Error, this might mean that the Redirect URI has not been configured properly in Step 1 of the preliminary setup. Make sure to revise it. Note that Space supports only HTTPS connection.

  3. The project creation wizard will display a list of all Space projects your user has access to. Choose a repository and wait until TeamCity verifies the connection settings.

  4. Now it's time to configure the main settings of the new project and its VCS root. You can always adjust them later.

    • Project name and the name of its first build configuration.

    • VCS root: (read-only) matches the URL of a repository you choose in Step 3.

    • Default branch: refs/heads/main, or another branch of your choice. Remember to keep refs/heads and change only the branch name.

    • Branch specification: if you want to run builds on other branches apart from the default one, this setting allows extending the scope of the VCS root to monitor these branches as well. TeamCity uses a special format or branch specification rules for this. To monitor the whole repository, use the refs/heads/* rule.

      Configure project settings

    tip

    Our sample project contains project settings specified in a TeamCity Kotlin DSL format. If TeamCity detects them in your repository, it can automatically apply the specification to the new project.

  5. Click Proceed.

TeamCity will attempt to autodetect build steps in your project. You can confirm or reject the proposed steps and explore the project settings further.

If you create a project from a repository automatically, like we just did, TeamCity automatically adds a VCS trigger. This trigger will be watching your Space repository and run builds on each new commit. You can edit its settings or add other types of triggers.

TeamCity will show the commits that got into a build on the build's Overview tab. Click the Space icon opposite a commit to open its details in JetBrains Space:

Create a connection to Space

After this basic setup, you can advance the Space integration by following the instructions below, or learn how to create more sophisticated build configurations and utilize the power of TeamCity to the fullest.

Building Sources from Merge Requests

A build's checkout scope usually consists of the following items: the default branch of VCS root(s) + the project's branch specification + checkout rules of the build configuration. By adding the Pull Request build feature to this build configuration, you can add one more item to this formula — branches of merge requests. This will allow TeamCity to monitor changes in merge requests and run builds on them. The most common use case for this is prebuilding and pretesting sources of feature branches before they are merged into the default branch.

To add this feature:

  1. Go to Build Configuration Settings | Build Features.

  2. Click Add build feature and choose Pull Requests.

  3. Choose the recently created VCS root.

  4. Select JetBrains Space as the VCS hosting type and specify the settings as follows:

    • Connection: choose the connection to Space.

    • By target branch: define the branch filter to monitor merge requests only on branches that match the specified criteria. If left empty, no filters apply.

  5. Save the settings.

warning

Note that the scope of branches you define in this feature should not overlap with the branch specification of the VCS root. This measure will ensure that no conflicts occur when starting builds on merge requests.

Now, TeamCity will monitor merge requests submitted from the source branches of your repository. If a build is run on a merge request, TeamCity will display the details of the request and report the build status to the code review in Space:

Reporting build statuses to Space

tip

To protect a JetBrains Space branch from unverified merge requests, you can also configure Quality Gates in your repository settings. If you set a TeamCity build as an external check, JetBrains Space will require the build on a merge request to finish successfully before allowing this request to be merged.

Read more about the Pull Requests build feature in this article.

Automatically Merging Request if Build is Successful

TeamCity can automatically merge a request into a target branch if the respective build finishes successfully. To achieve this:

  1. Go to Build Configuration Settings | Build Features.

  2. Click Add build feature and choose Automatic Merge.

  3. Specify what branches to monitor and to merge into.

  4. Choose a merge policy. You can find more information about advanced settings of this feature here.

  5. Save the settings.

Each time a build satisfies the conditions of the selected merge policy, TeamCity will merge it to the specified target branch.

Reporting Build Statuses to JetBrains Space

TeamCity can report statuses of builds to JetBrains Space. To achieve this:

  1. Go to Build Configuration Settings | Build Features.

  2. Click Add build feature and choose Commit Status Publisher.

  3. Select the JetBrains Space publisher and the connection to Space.

  4. Specify the name that will be displayed for this service in Space.

  5. Save the settings.

Now, whenever you run a build in this configuration, TeamCity will report the build status to JetBrains Space.

Display build status in JetBrains Space

Authenticating in TeamCity with JetBrains Space Account

Users of your JetBrains Space instance can authenticate in TeamCity with their Space accounts. Note that this functionality requires adding the JetBrains Space connection on the Root project level.

To configure it:

  1. Go to Administration | Authentication.

  2. Click Add module and choose the JetBrains Space type.

    Add a JetBrains Space authentication module

  3. Choose if you want to allow creating new users on the first login, if their emails are not recognized by TeamCity. Disabling this option could be helpful if you use a publicly available TeamCity server and want to limit access to it.

  4. Save the module.

To sign in to TeamCity, click the JetBrains Space icon above the TeamCity login form and, after the redirect, approve the TeamCity request.

Sign in to TeamCity with JetBrains Space account

See also

Administrator's Guide