GitHub Integration Tutorial

By integrating YouTrack with GitHub, YouTrack users gain the following benefits:

• Commit messages in GitHub can contain YouTrack commands that can be used to, e.g., close a fixed issue.
• These commit messages can also be acquired from pull requests.
• It is possible to provide direct links to GitHub commits using commit hashes.

Requirements

In order for the integration to work, your YouTrack installation must satisfy the following requirements:

• The YouTrack server should be publicly accessible on the Internet.
• The email addresses of the user in GitHub and YouTrack must match. Otherwise, the commands passed in the commit messages will not be applied.

Configuration

First, go into your project settings and choose the GitHub tab:

Now click the Add GitHub repository link. You will see the following window:

The above window requires an auth token. To make one, click the create OAuth token here link in the dialog. This takes you to GitHub. After providing the password, you should see the following:

Give the token a name and create one! You only get to see the token once, so copy it to the clipboard and paste it into the YouTrack repository selection window. You can now pick the repository to attach to:

Please note that, in the above, you are only seeing your own repositories. If you need to access organizational repositories, make sure you select the Show repositories for another owner check box.

Having chosen the repository, you can now see it in the repository listings. The repository shows its name, who maintains it, whether the hook is enabled, what branch it takes changes from, and who is part of the committers for this repo.

To edit some of the settings, click the Edit link.

Most of these settings are self-explanatory; the Process only distinct commits setting ensures that only distinct commits are processed, meaning that changes such as merges are not analyzed.

Click the Save button and you're ready to start working with GitHub integration.

Using the Integration

First of all, let's take a look at how to close an issue using a commit message. For this to work, we need two things:

• We need to know the exact ID of the issue we're about to change.
• We need to know exactly the command we want to send.

The ID part is fairly trivial, you can look it up in YouTrack. As far as IDs go, this is where things get interesting.

Essentially, on the most basic level, you can simply provide a set of commands (similar to what one would enter via the Command window), but prefixed by the hash (#) symbol and the issue ID, e.g.:

However, it would be unfair to constrain the user just by a set of commands for a single issue. So, the general syntax for sending commands is

In other words, a single commit message is capable of modifying several issues at once, each with a distinct commit message and set of commands being invoked.

Now for a hands-on example. Here's an issue that I have assigned to me:

Now I can go off and fix this issue. To do so, I provide a commit message which sets the issue state to Fixed, but also alters the Subsystem field to contain the value UI.

I also provide a comment which appears just before the issue identifier. What's more, in that comment, I actually refer to a previous GitHub commit via its hash:

If you are wondering how to get that hash to begin with, simply go into Commits in GitHub and press the Copy full SHA link next to the commit:

I now push my commits to the server and, when I get back to the issue, I see that my fields have been updated (issue has been changed to Fixed and the Subsystem has been changed to UI) and, in addition, the following comment gets added to the issue:

The above comment has a hyperlink to the current commit, but also, the other commit hash that we included got turned into a hyperlink as well.