How to Configure CI/CD for JetBrains Space

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.

You can connect TeamCity to JetBrains Space using two different techniques. The traditional approach includes two steps:

1. creating a service application for TeamCity authentication in your Space instance;

2. creating a preset of connection to Space.

Starting with version 2023.11, you can utilize semi-automatic Space connections that allow you to skip setting up Space applications manually. Instead, specify the organization URL (for Space On-Premises) or choose the required Cloud instance (for Space Cloud) and TeamCity will automatically create and install Space applications with all required permissions.

This tutorial explains how to manually setup the TeamCity-Space integration. For the detailed instructions on how to implement the Space integration using the newer semi-automatic approach, see this section instead: Configuring Connections, JetBrains Space.

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.
   

   

   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.

     

   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 shows 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:

If the commit mentions a Space code review tag (for example, JETBRAINS-DEMO-CR-3) or a Space merge request tag, you can click the tag to jump directly to the corresponding code review or merge request in Space. In particular, a merge commit from Space is always accompanied by a link back to the corresponding merge request.

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.

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:

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.

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.

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.
   

   

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.