Enabling GitHub Apps & Integrations
Advice for Chingu Voyage Project Managers
In your role as Project Manager’s in the Chingu Voyages your most important two tasks are to understand your teams needs and to remove any obstacles blocking their progress. Quite often both require help from additional tools and what better place to use those tools than GitHub, which is central to the teams efforts and is where they spend a considerable amount of their time.
A number of apps and integrations are available through GitHub and they fall into a number of different categories, all centered on the development process:
- Code quality
- Code review
- Continuous integration
- Dependency management
- Project management
- Recently added
What’s The Difference Between an App and an Integration?
Integrations integrate an external service with GitHub to provide a particular service via a Github app, webhook, or OAuth app. Integrations are enabled at the repository level. Any repository owner or admin can enable an integration and all Voyage project managers have administrative privileges on their teams repositories
In contrast GitHub apps extend and add functionality to existing GitHub workflows. When enabled, these are available not to just a single repository, but to and entire organization like Chingu Voyage3. Enabling a GitHub app requires owner or admin privilege on the organization. For obvious reasons these privileges aren’t available to all Chingus. As a result if you find an GitHub app you’d like to make use of add the request to your Voyage Issue Log.
You or your team may wish to take advantage of the apps and integrations available through GitHub to aid and enhance your development efforts and processes. However, before doing so make sure you:
- Choose a tool that you will use
- Choose a tool whose value exceeds the effort required to use it
- Understand the cost — not every tool is free!
- Understand the license agreement, especially how and when information is shared with outside parties
Remember that you installing integrations and apps should be done with purpose in mind. If you don’t need it, then don’t install it.
Enabling a GitHub App
Before you can enable an app you need to understand what apps are available by browsing the GitHub Marketplace. To navigate to the Marketplace click its name located in the banner at the top of every GitHub page.
Once at the Marketplace you can browse the available apps to find the one that best fits your teams need.
As you scroll down the page you’ll find options for searching by either name or category. In addition, those apps offering free trials are prominently listed as well. Keep in mind that many of these also offer free usage for open source and public projects such as those in the Chingu Voyages.
For the purposes of example we’re going to click on ‘Codecov’ to install it in the Chingu Voyage3 organization. One important note is while Codecov may offer many advantages to teams this is not an endorsement. We’re merely using it as an example of how to install a GitHub app.
Recall that since Codecov is an app it will be available not just to your team, but to all teams in this organization.
After selecting ‘Codecov’ you will be presented with an overview of important information about the app including what it does, how it will help your team, dependencies, and a link to the vendors website. If you decide that the app can help your team click ‘Set up a free trial’ to see pricing options.
Codecov happens to be an app that can be used at no charge to Open Source projects. When evaluating apps you will want to review the pricing and setup information carefully and make sure that you select ‘Open Source’ if it’s offered to avoid any charges.
When you are ready to install the app click ‘Install it for free’ on the right hand side of the page. Remember that only organizational owners and admins can enable apps. If you don’t hold either of these privileges add a request to your Voyage’s Issue Log and someone will enable the app for you.
Before completing the order you will be shown the following information summarizing your order. Make sure the cost and the organization you are installing this app in are correct. Once you’ve verified this select ‘Complete order and begin installation’.
Once you’ve placed your order for the app you’ll be given the opportunity to select the repositories it will be installed on, as well as a summary of the GitHub permissions that will be granted to the app on your behalf.
At this point select ‘Install’ to proceed or click on ‘cancel’ to stop the installation process. Cancelling is always a good option to take if you happen to be uncomfortable with the permissions that will be granted to the app.
Up to this point you’ve been on the GitHub site. However, after completing your order you’ll be redirected to the app vendors website to complete the installation. At this point the installation process could be different for each app, however you should expect to be prompted to login to GitHub.
Once authenticated on the app vendors website you will be prompted to authorize the app against one or more of your repositories. After completing this step the app will be connected to your GitHub repositories. But, you might still be prompted to complete additional, application-specific customization.
Use the Settings option on your GitHub organization and repositories to see which applications are installed, to manage access, and to uninstall.
Enabling a GitHub Integration
Any repository owner or admin, including a Voyage project manager, can enable an integration. To enable a GitHub integration on a repository select the ‘Settings’ tab on the repository you wish to integrate with the tool. Next, from the list of options on the left hand side of the Settings page select ‘Integrations & services’.
You will be presented with a page showing the services and apps you have previously installed. At this point you might be asking “Shouldn’t I have chosen the service to integrate with my repo before getting this far?”. Well the answer is “yes”, but unfortunately listing the services that are available to you are only shown on this page.
If you click on ‘Add service’ a drop down list of the available service integrations will be displayed. From here you can select the one you want, in our case ‘Trello’, to integrate it with your repository.
Before allowing the integration process to proceed GitHub will require you to enter your password. Even though you are already logged in to GitHub this is an additional protection to ensure no one is attempting to alter your repo while you are getting coffee.
Remember that you should have locked your computer before leaving it unattended!
You will now be presented with a page that describes the service you want to add and instructions for how to proceed with its installation. Read these carefully and as with apps make sure you understand the permissions that will be granted to the service and how it will consume and share your information.
GitHub apps and integrations can provide extremely useful functionality to you and your team. Functionality that’s note already part of GitHub and which will help to make your development process to be more smooth and efficient.
However, as the saying goes “With great power comes great responsibility”. It’s up to you as a project manager to make sure the tools you choose live up to their value proposition and that you understand the security and confidentiality implications of your choices.
Have fun in your Chingu Voyage, make mistakes and learn, and remember to use the team Slack if you have questions or need help!