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. To 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 recognized by YouTrack without leaving your IDE or repository.

This feature is supported by the following integrations:

For build server integrations, the availability of this feature is based on the configuration for the integration in your project. In the Processing for VCS changes settings, you must enable the option to Apply commands to issues in one or more mapped projects. Otherwise, the commands are ignored by YouTrack. To learn more about these settings and other configuration options, see Build Server Integration.

Matching VCS Change 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 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 username should be associated with the user profile in TeamCity.
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. First, YouTrack searches for a user account whose email address matches the email address of the commit author. If found, the command is executed on behalf of this user. If none of the users in the Committers group has such an email address, YouTrack tries to find a match by name. It takes the value provided by the integrated VCS and compares it to the list of VCS usernames that are stored in the Hub accounts for users who belong to the Committers group. GitHub and GitLab provide the value stored as the Name. Bitbucket provides the value stored as the Nickname.

Connection Type

Description

TeamCity Integration

YouTrack checks the email address 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 username should be associated with the user profile in TeamCity.

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.

First, YouTrack searches for a user account whose email address matches the email address of the commit author. If found, the command is executed on behalf of this user.
If none of the users in the Committers group has such an email address, YouTrack tries to find a match by name. It takes the value provided by the integrated VCS and compares it to the list of VCS usernames that are stored in the Hub accounts for users who belong to the Committers group.
- GitHub and GitLab provide the value stored as the Name.
- Bitbucket provides the value stored as the Nickname.

If the author of the commit message cannot be found in YouTrack, the command is not applied. The username 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 usernames in their Hub accounts.
GitHub and GitLab users often enter their username instead of the value 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 usernames 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 usernames in YouTrack, not torvalds, which is his username in GitHub.

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]
...

[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 is 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 Parse commits for issue comments option is enabled for your integration, any text 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.

The following example shows a commit message where the issue ID and summary are used as the commit message text, followed by a command that changes the state of the issue to Ready:

RD-2677 article and formatting issues #RD-2677 Ready

Updating Multiple Issues

You can also apply commands to multiple issues by grouping issues by ID in parentheses. You don't need to 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 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 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.

Last modified: 09 October 2024