GitHub Integration: why and how
Many teams tend to use GitHub pull requests for reviewing code changes, and it is completely understandable. GitHub is a popular choice for hosting Git repositories, and teams that keep their projects on GitHub naturally start to manage code reviews via pull requests. However, while GitHub has excellent Git hosting functionality, we believe that as far as code reviews go, there’s a lot that could be better. Upsource on the other hand provides a rich set of code review assistance features, code insight for popular programming languages and top-notch IDE integration. However, all those things were previously available only to teams using post-commit and branch review approaches. We have received a number of requests to add support for GitHub pull requests in Upsource, and we are happy to be able to offer it to you in Upsource 3.0.
Why review GitHub pull requests in Upsource?
If you haven’t tried Upsource yet, you may be wondering how exactly can Upsource make reviewing a pull request easier for you?
Upsource can even show which new potential issues were introduced with this particular revision, and which problems have been fixed.
You can navigate through the code to better understand it, just like you would in an IDE, and see where symbols are used:
Upsource will even let you know how a change affected usages of a symbol.
No other code review tool can offer you this much insight into your code and help you understand a change on so many levels. Basically you have the power of your IDE at your fingertips while looking at code in your browser.
Code review is an iterative process, it’s rarely the case that a pull request contains only one revision. Most of the times there are multiple changes, and a reviewer has to come back to them time and again. Upsource helps you track what you already have seen. When you’re done with yet another iteration and raised a concern, next time there’s a new change, Upsource will only show you the new change, not the summary of all changes. Naturally, it is also possible to pick and choose which changes you want to see. You can see all of them, latest, or, perhaps, you only want to come back to that particular change somewhere in the middle of it all? That’s possible too!
Within current iteration Upsource also tracks read/unread files for you.
Upsource provides a clear way for the reviewers to indicate whether they are happy with a change, or there’s still something to be addressed.
Comment threads work well in GitHub, but a reviewer has to use emoji to indicate whether they are satisfied with the outcome of a discussion. Upsource provides a way to resolve discussions, and label them to categorize and prioritize any concerns raised during a review.
It also maintains the position of an unresolved discussion in the file, so that you could come back to it later, outside of the scope of the review.
Upsource doesn’t spam your inbox as notifications are bundled and sent as a digest instead of being sent immediately. You can also specify which events you wish to receive notifications about. The notifications that you receive in your News Feed, be it in your browser, or in your Upsource IDE plugin, are delivered in real time, so that you can have a real-time discussion in the context of an actual change.
How does it work?
When connected to a project hosted on GitHub, Upsource synchronizes the following user activities:
- Discussion comments posted in GitHub are shown in Upsource and vice versa
- Pull requests can be created right form Upsource, existing pull requests are also recognized.
- A branch review is automatically created on a new pull request
On a side note, this also means that if part of your team wants to use Upsource while some team members prefer reviewing pull requests in GitHub, this is possible too. Upsource in no way prevents you from continuing using pull requests on GitHub.
Where to start?
To begin reviewing your GitHub pull requests with Upsource you need two things – a repository in GitHub, and an instance of Upsource installed on your servers or your own cloud infrastructure.
To enable the integration and make sure user activities are synchronized, you need to:
- Set up GitHub authentication module: see our documentation for details.
- Connect Upsource to your repository by filling out a couple of fields:
Make sure to provide a token that will be used for reading data from GitHub – anonymous access is generally not recommended.
- Your users will see Login to GitHub button on the project’s main page. They will need to login to GitHub from Upsource so that their comments and other activities are reflected on GitHub.
If you’ve checked the “Import pull requests as branches” option, Upsource will create code reviews for existing pull requests automatically. You can also create new pull requests from Upsource for existing branches, and merge pull requests, if there are no conflicts found.
Enjoy your code reviews!