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.
Configure an Application for YouTrack in Space
To connect YouTrack to Space, you need to register and configure an application in Space.
To register and configure an application for YouTrack in Space:
In Space, open the Administration menu and select Applications.
Click the New application button.
Give your application a unique name and click the Create button.
A new application in Space is created.
Click the Go to application button to open the application settings.
Open the Authorization tab.
In the In-context Authorization section of the page, click the Configure requirements button.
In the Required Permissions dialog, enable the following permissions:
In the Project category: View project details.
In the Git Repositories category: Read Git repositories, Write Git repositories, and Manage Git repositories.
Click the Save and request button to close the dialog.
Click the Authorize in project button.
The Authorize in Project dialog opens.
From the drop-down list, select the project that contains the repository that you want to integrate with your YouTrack project.
Click the Authorize button.
You are navigated to the page that lists permissions for your application in the selected project.
The application is given authorization to perform the actions required for this integration in the selected project.
Go to the Authentication tab in the application settings and prepare to copy the client ID and secret to YouTrack.
If you already have an application for YouTrack in Space, make sure that it is configured according to the instructions provided here and prepare to copy its client ID and secret to YouTrack.
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 client ID and secret from the application settings in Space. These credentials allow YouTrack to access the repository according to the rights granted to the application in Space.
To connect to a Space repository:
Open the
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 the client ID from Space into the Application client ID input field.
Paste the client secret from Space into the Application client secret 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 | Choose how to process VCS changes when the commit message references an issue ID. The following options are supported:
|
Monitored branches | Stores the names of the branches that you want to monitor for changes.
If the address that you entered as the Repository URL when you connected to the repository 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 | 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:
To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits. |
Check branch names for issue references | When enabled, the integration checks for references to issues in branch names for commits and pull requests. This option was added for teams that use a branch-per-ticket process, so their developers don't have to mention issue IDs in their commit messages explicitly. |
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. |
Available Actions
When you select an integrated version control system in the list, the following actions are available in the toolbar:
Action | Description |
---|---|
Disable | Shuts off the connection between the integrated project and the VCS repository. The configuration is not changed and can be enabled at any time. |
Edit | Opens the integration settings dialog in the sidebar for the selected project and repository. |
Delete | Removes the settings for the integrated project from YouTrack. This action also removes all VCS changes that were added to issues for commits in the linked repository. While the action itself cannot be undone, you can use the Import action to restore VCS changes that were removed accidentally. |