How to Configure CI/CD for JetBrains Space
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.
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:
creating a service application for TeamCity authentication in your Space instance;
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.
In your JetBrains Space instance:
On the navigation bar, click Extensions and choose Installed to organization.
Click New application.
Enter a convenient name (for example,
Space-to-TeamCity
), save the application, and click Go to application settings.Configure In-context Authorization:
On the Authorization tab, click Authorize in new context.
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.
(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.
Configure Global Authorization:
On the Authorization tab, click Configure.
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.
Configure Authentication Mode:
Go back to the app's Overview and open the Authentication tab.
Enable Client Credentials Flow.
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.tip
To ensure that your TeamCity server can always connect to JetBrains Space, it is important to specify all the other possible endpoint addresses of the server. In most cases, it would be enough to specify the Server URL set in Global Settings in TeamCity. However, if you use a proxy for your TeamCity server but access this server directly, the authentication might not work unless the server's IP address is also specified here.
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.
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:
Go to Project Settings | Connections and click Add Сonnection.
Choose the JetBrains Space connection type.
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.
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.
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:
Click From JetBrains Space.
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.
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.
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 keeprefs/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.
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:
Navigate to Administration | <Your Configuration> to access build configuration settings.
Open the Build Features settings tab.
Click Add build feature and choose Pull Requests.
Choose the recently created VCS root.
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.
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 automatically merge a request into a target branch if the respective build finishes successfully. To achieve this:
Navigate to Administration | <Your Configuration> to access build configuration settings.
Open the Build Features settings tab.
Click Add build feature and choose Automatic Merge.
Specify what branches to monitor and to merge into.
Choose a merge policy. You can find more information about advanced settings of this feature here.
Save the settings.
Each time a build satisfies the conditions of the selected merge policy, TeamCity will merge it to the specified target branch.
TeamCity can report statuses of builds to JetBrains Space. To achieve this:
Navigate to Administration | <Your Configuration> to access build configuration settings.
Open the Build Features settings tab.
Click Add build feature and choose Commit Status Publisher.
Select the JetBrains Space publisher and the connection to Space.
Specify the name that will be displayed for this service in Space.
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:
Go to Administration | Authentication.
Click Add module and choose the JetBrains Space type.
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.
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.
Thanks for your feedback!