Codiga Migration to GitHub App

In this article, we explain how Codiga migrated its GitHub OAuth app into a pure GitHub app (you can read more about the differences between these two types of applications here). Additionally, we'll explain the reasons that motivated us to do so, as well as the technical logistics that were required for a smooth migration.

Background

In early 2019, we decided to support GitHub not only as a way to authenticate on Codiga but also to add your new repositories on regular account (when authenticating via e-mail). With GitHub being the central marketplace for most developers today, it seemed natural for us to support it.

At the time, we decided to use the OAuth app method. The main reason was because of the large amount of documentation available for OAuth and the possibility to reuse shared libraries on OAuth authentication. In fact, it is easy to find libraries for almost any language to support OAuth.

However, quickly, we got reports from users complaining about this choice: a GitHub OAuth App gives access to all repositories on their account while they wanted to restrict access to a subset of their repositories (a GitHub App allows to restrict the repositories used for the App). In addition, a GitHub OAuth app does not restrict the lifetime of their token so if a malicious user able to find or guess the OAuth token, they could access their code. In comparison, a GitHub App uses short-lived token (10 minutes max) that needs to be periodically generated. With everything we do at Codiga, security is always our top priority, so ths was the driving force that motivated us to switch from the original OAuth app to a GitHub App.

Migration Plan

Our plan was to have a smooth transition that would avoid any service disruption for our users. We migrated in several steps:

1. Create a new GitHub App
2. Implement authentication for the GitHub app on our front-end and back-end. We added a flag in our back-end to distinguish users using the GitHub App and the users that use the OAuth app.
3. Implement a migration path: for any existing user that install the new GitHub App, we automatically revoke the permissions from the previous app.
4. Notify our users of the migration
5. Switch our GitHub marketplace listing from a GitHub OAuth App to GitHub App.

All the code that was implemented within the new GitHub App, as well as the migration path, has been tested meticulously: all the code was unit tested and we did integration testing on our end, ensuring that our users will not encounter any issue.

How did it go?

What took a significant amount of time was the implementation of the new authentication system as well as the implementation of new webhooks that are specific to the GitHub App. The development effort took us one week, with an additional week to correctly test.

The major difference comes from the authentication system for GitHub Apps: their token is short-lived and it is necessary to periodically renew the tokens whenever you need them. Also, considering our platform is made of several micro-services, we wanted to avoid generating multiple short-lived keys for each individual product. To avoid this, we implemented a secure distributed cache to share these short-lived keys. That way, we only generate a new key when needed and this key is used by all our micro-services once the old one expires.

On the user side, the migration went well. No user complained and several of them were happy to learn about our efforts to migrate to a GitHub App for security reasons.

Feedback

Overall, this migration has been very easy and straightforward. It is important to have both unit and functional tests to make sure everything is working correctly. In particular for the webhook, which is a major component of a GitHub App: it is vital to make sure your webhook works as expected. GitHub shows all the API calls (with the payload) made on your webhook and lets you replay them: we used this data to design all of our test cases for the new GitHub App webhook.

In order to have a smooth transition between the OAuth App and GitHub App, you need to differentiate accounts that installed the new App. After doing so, you can automatically select old accounts to transition to the new Github App. This can be done by adding a simple flag on your database (that is set to a special value when the user installs the new App). This offers old users a transition path to the new GitHub App, ensures a seamless migration, and avoids user frustration when facing a firm migration deadline.

Lastly, it is important to consider the GitHub API may fail (for whatever reason — network failure, intermittent unavailability, etc) so you need to take that into consideration (re-try logic for failed requests, etc.). Thankfully, the GitHub API is very robust and to this day, we have never experienced an API failure from this end.

Moving forward

Our next step is to get our new GitHub App verified by GitHub, which should happen very soon considering our application meets the verification requirements. We invested massively on GitHub and will continue to do so: after our recent automatic code-review feature, we are now building new, exciting features that will help to have better visualization of your software architecture.