YouTrack InCloud 2018.3 Help

Apply Commands in VCS Commits

You can apply commands to issues when you enter a comment and commit updates to a code repository in a version control system. You don't even need to open YouTrack. 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:

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.

To process the commands, YouTrack has to find a user account that matches the author of the commit message. The command is applied based on the access permissions that are granted to the YouTrack account. 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.

You can subscribe to notifications that inform you when issues are updated in a build that is processed by YouTrack. For more information, see General Notification Scheme.

VCS Integrations

YouTrack matches the VCS user name of the user who committed the change to the list of VCS user names that are stored in the Hub accounts that are connected to YouTrack.

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 instructions that you can follow to resolve the problem.

VCS user not found

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 commit message 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 commit message. This text is not applied as a comment to the issue. The complete VCS commit message is displayed in the list of VCS changes in the activity stream.

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.

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.

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.

Last modified: 14 November 2018

See Also