YouTrack Standalone 2018.3 Help

GitHub Integration

A GitHub integration enables the following features in YouTrack:

  • Apply commands to YouTrack issues right from a commit comment or a pull request description. For more information, see Apply Commands in VCS Commits.

  • Track commits that are related to specific issues in the activity stream for the issue in YouTrack. For more information, see View and Edit VCS Changes.

  • Add links to YouTrack issues in commit messages. For more information, see Link Issues in VCS Commits.

  • Add links to the GitHub repository by pasting commit hashes into the summary, description, comment, or string-type custom field in YouTrack issues.

Prerequisites

  • Your YouTrack server must be accessible from the Internet.

  • A committer's email address in YouTrack must be the same as in GitHub. YouTrack searches for a user account based on the email address that is registered in GitHub. These users must also have permission to update issues in the connected YouTrack project. If no match is found or the user does not have the required permission, the commands are not applied.

Configure the GitHub Integration

When you enable and configure the GitHub integration, you define mappings between a YouTrack project and a GitHub repository. This operation can also be performed by a project administrator on a per-project basis. For more information, see Integrate with GitHub.

As an administrator, you can enable the GitHub integration for any project in YouTrack.

To enable and configure the GitHub integration:

  1. Open the Administration > VCS Integrations page.

  2. Click the New VCS Integration button.
    • The New VCS Integration dialog opens in the sidebar.

      new GitHub VCS integration

  3. From the Server drop-down list, select github.com.

  4. Generate an OAuth token in GitHub:
    • Click the Create OAuth token link below the OAuth Token field to navigate to GitHub.

      generate token in GitHub

    • Enter a description for the OAuth token.

    • Select the scopes for the OAuth token and click the Generate token button.

    • Copy the token to the clipboard.

      copy token in GitHub

  5. Paste the token in the OAuth Token field.

  6. If you are not the repository owner, provide the repository owner name. If you are the owner of the repository, leave the field blank.

  7. Click the Connect to VCS server button.
    • The New VCS Integration dialog displays settings for mapping the VCS to your project.

      GitHub integration settings

  8. Enter values for the following settings:

    Setting

    Description

    YouTrack Project

    Select the YouTrack project that you use to track changes to the code repository.

    Repository

    Select the repository where you store the source code that is related to the selected project.

    Committers

    Select the group that contains all of the users who can commit changes to the selected repository.

    Monitor Branches

    Enter the names of the branches that you want to monitor for changes. Use the plus sign to include a branch and the minus sign to exclude a branch. For more information, see Monitor Branches.

    Parse commits for issue comments

    To detect and generate issue comments from commit messages, enable this option. Otherwise, the entire commit message is displayed with the VCS change in the issue activity stream.

    We recommend that you only enable this option when:
    • You want to mention other users in your commit messages and generate notifications when the text is copied to an issue comment.

    • You restrict the visibility for VCS changes and want to make commit-related information visible to external users as comments.

    To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.

    Visible for Groups

    Select one or mor groups to restrict the visibility of VCS changes. Otherwise, the list of VCS changes is visible to any user who has permission to read issues in the project.

  9. Click the Save button.
    • The GitHub repository is associated with the selected YouTrack project.

      GitHub integration saved

Last modified: 12 October 2018

See Also