YouTrack Server 2023.3 Help

View and Edit VCS Changes

The activity stream shows a list of VCS changes that are associated with the current issue. These events are visible when the VCS changes filter is enabled. This information is only available when the project is integrated with a version control system. YouTrack can integrate with a version control system directly, or through another application that is connected to version control, like TeamCity, or Jenkins.

If the visibility setting for the integration is restricted to one or more groups, you only see the VCS changes if you are a member of one of the specified groups.

VCS changes are added to issues automatically when the issue is mentioned, when changes are committed to a branch containing the issue ID in its name, or when a command is applied to an issue in a commit message or pull/merge request. Use this information to track the changes in your code base that are related to each issue.

VCS changes activity stream

Commits

Commits are added to the collection of VCS changes whenever the issue is referenced in a commit message or a branch name. For more details on how to reference issues in commits, see Reference Issues.

The following information is displayed for commits that reference the current issue:

  • The name of the user who committed the changes to the repository.

  • The date and time when the commit was retrieved from the repository.

  • The commit message that was entered for the VCS change.

When you move the pointer over the commit event in the activity stream, additional actions are shown in the toolbar:

Action

Description

View commit

This control shows the abbreviated commit hash that is assigned to the VCS change. Click the hash to view the change details in the connected resource. When commits are recorded in more than one resource, click the down arrow and choose the resource that you want to open.

View additional info

Move the pointer over the info icon to see additional details. This action is shown for commits that were added manually or contain errors.

Detach

Removes the VCS change from the current issue. When the commit message contains the issue ID, the commit is detached but remains visible in the activity stream in a dimmed state.

Move

Opens the Move Commit dialog. This gives you the ability to remove the commit from the current issue and attach it to another issue instead

For more information, see Move a Commit to Another Issue.

Commits that contain errors are highlighted on the page.

  • If the VCS user that pushed the changes to the repository cannot be matched to a YouTrack user account, the username is shown in red text. The warning tooltip provides instructions that you can follow to resolve the problem.

  • If the commit message includes a command that could not be applied to the issue, the command is shown in red text. The warning tooltip shows which part of the command was not recognized.

Add Commits Manually

The activity stream automatically displays changes that mention an issue in the VCS commit message or in the branch name or apply a command to an issue in the VCS commit message. If there are changes that are related to an issue that were not added to the list of VCS changes automatically, you can add them manually.

To add a commit manually:

  1. Open the issue in single issue view.

  2. From the Show more menu, select the Add commit option.

    Add commit manually
    • The Add Commit dialog opens.

  3. Enter or paste the hash for the commit in the VCS repository.

    Add commit
  4. Click the Add button.

    • The revision is added to the list of VCS changes.

Move a Commit to Another Issue

If you accidentally reference the wrong issue ID in your commit message, the VCS change doesn't appear where it should. When mistakes like this happen, all you have to do is move the commit to the correct issue.

To move a commit to another issue:

  1. Locate the commit in the VCS Changes section of the issue activity stream.

  2. Click the Move icon in the toolbar for the VCS change event.

    • The Move Commit dialog opens.

    Dialog for moving commit to another issue.
  3. Enter the ID of the target issue in the input field provided.

  4. Click the Move button.

    • The commit is removed from the current issue and added to the collection of VCS changes that are attached to the target issue.

Pull Requests

Pull requests (which in some version control systems are called merge requests) are added to the collection of VCS changes whenever the issue is included in the title or description of the pull request.

Pull request in issue activity stream.

The following information is displayed for pull requests that reference the current issue.

  • The name of the user who submitted the pull request or performed an action related to an existing pull request.

  • The action performed with the associated the date and time.

  • The reference ID for the pull request, formatted as a link to the object in the integrated version control system.

  • The pull request description.

Even though pull requests and commits are shown together on the VCS tab of the activity stream, they are handled in different ways.

  • YouTrack doesn't parse the title and description of the pull request for issue-related commands. Whatever text is written in these fields is formatted in Markdown and shown in the activity stream. Anything that would be processed as a command when included in a commit message is ignored.

  • Pull requests cannot be attached to an issue manually or moved to another issue. Instead, these references are updated automatically when a user edits the title or description of the pull request in the linked version control system.

Reference Issues

When you want to link your changes to an issue, reference the issue ID along with your commit. There are the following options to reference an issue ID:

Reference Location

Details

Commit message

You can reference an issue ID in a commit message in two ways:

  • Type the issue ID in the commit message. For example, NP-1234 test fixes.

  • Use special formatting in the commit message to reference the issue and apply a command to it simultaneously. For example, #TST-345 Fixed. For more details about applying commands in commit messages, see Apply Commands in VCS Commits.

Branch name

When YouTrack doesn't find any issue references in the commit message, it checks the name of the branch for an issue ID. If the branch name contains an issue ID, the commit gets attached to this issue. Any commands in the commit message are ignored in this case.

To enable referencing issues by branch names, enable the Check branch names for issue references feature in the VCS integration settings. For details, see VCS Integration.

Pull request title and description

YouTrack checks the title and the description of the pull request for an issue ID and attaches the pull request to the mentioned issue. Any commands in the title and description of the pull request are ignored. For more details on handling pull requests, see Pull Requests.

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 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 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 that is 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 that is stored as the Name.

    • Bitbucket provides the value that is 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.

VCS user not found

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.

Last modified: 22 March 2024