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:
|
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
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.07, 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.
Step 1: Create Application in 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.
(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.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
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.
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:
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.
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/headsand 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.
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.
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:
Go to Build Configuration Settings | Build Features.
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.
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:
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:
Go to Build Configuration Settings | Build Features.
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.
Reporting Build Statuses to JetBrains Space
TeamCity can report statuses of builds to JetBrains Space. To achieve this:
Go to Build Configuration Settings | Build Features.
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.
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:
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.
