Space Integration

Follow the instructions on this page to integrate with VCS repositories that are hosted on JetBrains Space.

A Space integration enables the following features in YouTrack:

Apply commands to YouTrack issues in commit messages. For more information, see Apply Commands in VCS Commits.
Track commits that are related to specific issues in the activity stream for the issue in YouTrack. For more information, see Commits.
Add links to the Space repository by pasting commit hashes into the issue summary, description, comment, or a supplemental text field.

Prerequisites

YouTrack is accessible to inbound connections. Specifically, you need to make sure that your network doesn't block connections between your VCS server and YouTrack.

Also, to establish a connection to a Space repository, you must generate a Personal token in JetBrains Space:

In Space, log in as a user that you will use to enable VCS integration. Open their user profile and then switch to the Personal token page.
Click the New personal token... button to open the New Personal Token dialogue.
Enter a name for the token.
In the Token permissions section, enable Limited access option. Then, select the following permissions: ViewProject and VCSAdmin.
Click the Create button.
Copy the token to a safe place as it is the only time when it is visible.

Connect to a Repository

The first step is to establish a connection between a project in YouTrack and a repository in Space. To connect with Space, you need the personal token that you have preliminary generated. This token grants YouTrack access to the repository based on the access that is granted to your Space account.

You can use a single access token to set up multiple integrations.

To connect to a Space repository:

Open the Administration > VCS Integrations page in YouTrack.
Click the New VCS Integration button.
- The New VCS Integration dialog opens.
From the Main YouTrack project list, select the name of the primary project that you want to integrate with the VCS repository. You can add integrations with additional YouTrack projects after you have set up the connection to the repository.
For the Server type, select Space.
Paste the URL that points to your Space repository into the Repository URL input field.
Paste your personal access token into the Personal token input field.
Click the Save button.
- Your YouTrack project is integrated with the selected repository in Space.
- Commits from the Space repository that reference an issue in the project are displayed in the activity stream of the referenced issue.
- The sidebar displays additional settings for configuring the VCS integration.

Integration Settings

By default, the VCS integration processes changes that are committed to the repository by any user in any branch. Any user who has access to the issue in YouTrack can view these changes in the issue activity stream.

If you only want to process changes by specific users in designated branches or restrict the visibility of VCS changes in YouTrack, you can customize the integration settings. Use following settings to customize the integration:

Setting	Description
Repository	Displays the path to the repository in the integrated version control system. If needed, you can edit the location of the repository after you have set up the integration. For instructions, see Edit Repository Settings.
Main YouTrack project	Sets the primary project in which the VCS integration is active.
Additional projects	Integrates the linked repository with one or more additional projects.
Committers	Restricts the ability to update issues with commands in commit messages to members of the specified group. VCS changes from users who are not members of the selected group are still attached to related issues, but any commands that are specified in their commits are ignored.
Processing scheme for VCS changes	Select the way how YouTrack processes VCS changes with commit message that references ID of an issue. The following options are supported: Add commits, ignore commands: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Any command in the commit message is ignored. Add commits in all projects, apply commands in main: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Only apply commands to issues that belong to the currently selected main project. When this option is selected, the Parse commits for issue comments option becomes available. Add commits and apply commands to all projects: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Update issues in any integrated project when commit messages include commands. Scheme is available only when at least one Additional project is specified in the integration settings. When this option is selected, the Parse commits for issue comments option becomes available.
Monitored branches	Stores the names of the branches that you want to monitor for changes. Use `+` to include a branch. Use `-` exclude a branch. For the `branch name`, use the fully qualified name of the branch. For example, `refs/heads/<branch name>`. Use `` as a wildcard. This placeholder matches one or more characters in a string. For example, to include all feature branches, use: +:refs/heads/feature/ To monitor all branches, leave the input field empty. If the address that you entered as the Repository URL when you connected to GitHub points to a specific branch, this branch is automatically added to the list of monitored branches when you set up the connection.
Parse commits for issue comments	This option is shown in the UI only when either of the following processing schemes is selected: Add commits in all projects, apply commands in main Add commits and apply commands to all projects When enabled, specific segments of commit message text are copied to issues as comments. When you copy parts of the commit message to the issue as comments, you can trigger @mention notifications and expose information to users who don't have access to VCS changes. This setting does not affect how commit messages are shown in VCS changes. The entire commit message, including commands and issue comments, is always shown as part of the VCS change record in the activity stream. You should only enable this option when: You want to mention other users in your commit messages and generate notifications when the text is copied to an issue comment. You restrict the visibility for VCS changes and want to make commit-related information visible to external users as comments. To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.
VCS changes visibility	Restricts the visibility of VCS changes to one or more groups of users in YouTrack. When unrestricted, the list of VCS changes is visible to any user who has permission to read the issue.

Last modified: 30 March 2021