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.
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)
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. |
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 | 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 profiles 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.
Command Syntax
Use the following syntax to apply commands to issues from a VCS commit message:
[VCS comment text] #issueID [command 1] [command 2] ... [command n]
[issue comment text]
...or
[VCS comment text] ^issueID [command 1] [command 2] ... [command n]
[issue comment text]
...The commit message is broken down into the following components:
Component | Description |
|---|---|
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. 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. |
VCS comment 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 on the VCS changes tab. |
Issue comment text | Text that is added as a new line after a command is added to the issue as a comment. You can add multiple lines of text between commands. |
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 VCS 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}
Hooray! 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 enter a placeholder in a commit message. The placeholder is replaced with the corresponding value in the connected version control system when the commit message is processed by YouTrack. The following placeholders are available:
Placeholder | Description |
|---|---|
${build.time} | The date and time of the build that contains the VCS commit. |
${prev.build.time} | The date and time of the build prior to the build that contains the VCS commit. |
${build} | The number of the build that contains the VCS commit. |
${revision} | The revision number that is assigned to the VCS commit. |