Apply Commands in VCS Commits
You can apply commands to issues when you commit changes to a code repository in a version control system. You don't even need to open YouTrack. Do apply these changes, you use a special format to specify a command in your commit message. For a complete list of commands that are supported in YouTrack, see Command Reference.
You may have already seen how to add links to issues in a commit message. This goes one step further. Instead of just adding links that help you navigate between your issues and the version control system, you can apply any command that is recognized by YouTrack without leaving your IDE or repository.
This feature is supported by the following integrations:
- TeamCity Integration
- Upsource Integration
VCS Integrations (GitHub, Bitbucket, and GitLab)
For build server integrations, the availability of this feature is based on the configuration for the integration in your project. Specifically, the Process changes setting for the mapping between the build configuration and the project must be set to Attach and apply commands. Otherwise, the commands are ignored by YouTrack.
Matching VCS Commit Authors and YouTrack Users
To link VCS changes and process commands in commit messages, YouTrack has to find a user account that matches the author of the commit message. If a command is specified in the commit message, it is applied based on the access permissions that are granted to the user account in YouTrack. The user account is identified in different ways based on the type of connection to the version control system.
Connection Type | Description |
|---|---|
TeamCity Integration | YouTrack checks the email address that is stored in the TeamCity user profile of the user who committed changes to the VCS. To recognize the TeamCity user who committed the change, the VCS user name should be associated with the user profile in TeamCity. |
Upsource Integration | This integration is supported by connecting to an external Hub that manages user accounts for both Upsource and YouTrack. The command is applied in YouTrack by the same user who entered the command in the VCS commit message. |
VCS Integrations | For VCS integrations, the ability to apply commands to issues is limited to users who are members of the Committers group in the VCS integration settings.
|
If the author of the commit message cannot be found in YouTrack, the command is not applied. The user name is shown in red text on the VCS changes tab. The warning tooltip provides information that you can use to fix the problem.
There are basically two things that users can do to fix this problem:
Use the same email address for their accounts in YouTrack and the integrated VCS.
Add their name (or nickname for Bitbucket) to the list of VCS user names in their Hub accounts.
note
GitHub and GitLab users often enter their username instead of the value that is stored as the Name in their profile. If you continue to have trouble applying commands in commit messages to your GitHub or GitLab repository, check your VCS user names for your Name.
For example, if the legendary software engineer Linus Torvalds wanted to make sure his GitHub commits were properly linked to his VCS changes, he would need to add Linus Torvalds to the list of VCS user names in YouTrack, not
torvalds, which is his username in GitHub.
Command-related Notifications
There are special event categories that let you monitor whether changes are applied to issues by VCS and build server integrations. The subscription options for these events are available in your YouTrack profile settings.
The following options are available:
Notification event | Description |
|---|---|
Updates applied by VCS and build server integrations | Sends a notification when a change is applied to an issue with a command that is entered in a comment in a VCS commit. This can help you verify whether your changes have been processed by the integrated build server or VCS. |
Failed commands in commits processed by VCS and build server integrations | Sends a notification when a command that is entered in a comment in a VCS commit fails to update an issue. This can help you identify users whose VCS usernames aren't properly matched with their YouTrack accounts or recognize invalid command syntax. |
To learn how to update the notification settings in your YouTrack profile, see General Notification Scheme.
Command Syntax
The settings for your VCS or build server integration include an option to parse commits for issue comments. With the Parse commits for issue comments enabled, commit message text that starts a new line after a command is copied to a separate issue comment. This feature can be enabled or disabled independently on a per-project basis and is disabled by default. To learn more, see Generate Comments from VCS Commits.
The pattern that you use to apply commands to issues is not affected by this setting. Use the following syntax to apply commands to issues from a VCS commit message:
[commit message text] #issueID [command 1] [command 2] ... [command n]
[issue comment text]
...or
[commit message text] ^issueID [command 1] [command 2] ... [command n]
[issue comment text]
...The entire commit message, including commands and issue comments, is shown as part of the VCS change record in the activity stream.
The message text is broken down into the following components:
Component | Description |
|---|---|
Commit message text | The string of characters that precedes the number sign or caret are simply added to the VCS change record. This text is not applied as a comment to the issue. The commit message text can wrap multiple lines and include empty lines. |
Commands | YouTrack recognizes the number sign (#) or caret (^) as a flag for an issue that is followed by a command. The characters that follow the number sign or caret are parsed to match an issue ID. Any string that follows the issue ID is parsed as a command up to the end of the current line. If any part of the command wraps to the next line, the command is truncated. You can apply additional commands to one or more issues by starting a new line with the number sign or caret. If the string contains any incorrect commands or attribute references, the command is not applied. Errors in the command are highlighted on the VCS changes tab. For a complete list of commands that are supported in YouTrack, see Command Reference. |
Issue comment text | If the the Parse commits for issue comments option is enabled for your integration, text that is added as a new line after a command is copied to the issue as a comment. You can add multiple lines of text between commands. If this option is disabled in your project, the text is only visible as part of the VCS change record. For more information, see Generate Comments from VCS Commits. |
Issue IDs | Any issue ID that is found in the commit message is transformed into a hyperlink. This includes issues that are flagged for a command and issues that are simply mentioned in the commit message or issue comment text. |
Updating Multiple Issues
You can also apply commands to multiple issues by grouping issues by ID in parentheses. You don't need so specify the same command to each issue individually. For example:
(#TST-12, #TST-324, #TST-433) Fixed Reviewed by john.d Revision ${revision}The command in this example is applied to three issues. The issue state is set to Fixed, the Reviewed by field is set to john.d. The value for the Revision field is automatically set to the current revision with the ${revision} placeholder.
The following example shows you how to update issues like a boss. A single commit message applies all of these changes at once:
For issue TST-345, the state is set to Fixed, the developer who reviewed the changes is added to the Reviewed by field, the revision number from TeamCity is added to the Revision field, and a comment is added to the issue.
For issues TST-423 and TST-348, the state is set to In Progress and a comment is added to both issues.
With this commit I've made the following progress:
#TST-345 Fixed Reviewed by daria.s Revision ${revision}
@William_Johnson I finally fixed this nasty bug!!!
(#TST-423, #TST-348) In Progress
I implemented the code to support this use case, but need to describe the steps for testing.Placeholders
You can use the ${revision} a placeholder in a commit message. The placeholder is be replaced with the actual hash of the VCS commit.
The TeamCity Integration supports additional placeholders for build attributes. These placeholders are used in commands that are automatically applied to all issues that are assigned build numbers in YouTrack. You cannot use these additional placeholders in manual commit messages. For more information, see TeamCity Integration.