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.
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.
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:
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.
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
none [some comment text] #issueID <command_1> [command_2]... [command_n] [some comment text] #otherIssueID <command_1> [command_2]... [command_n]...
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
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:
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.