Integrating Swarmia with your tools
      Back to home
      1. Help Center
      2. Getting Started
      3. Integrating Swarmia with your tools

      Integrating with GitHub

      Learn how to install Swarmia for GitHub

      Installing Swarmia for GitHub Cloud 

      To install Swarmia, make sure you have the necessary admin permissions on GitHub and find Swarmia in the GitHub Marketplace. Click Install, review the necessary authorizations, and click Install & Authorize. You will then be taken to the onboarding wizard. Give a name for your organization and click Next.

      💁‍♀️ Review your GitHub Enterprise Membership. Swarmia uses GitHub to manage access to the app. Ensure that all your intended Swarmia users have a GitHub account and belong to your GitHub organization. 

      ⚠️ Note: All users in your organization can read the metadata (such as Pull Request names) for all integrated repositories in Swarmia. Use caution if working with sensitive repositories.

      ⚠️ Note: Swarmia collects the file names and size of commits from the source code. We do not store your source code! More information is available on the Data Security page.

      ⚠️ Note: If you have open source projects and don't want to see data from them in Swarmia, you can manually select the repositories you want to connect during onboarding.

       

       

      Installing Swarmia on GitHub Self-Hosted Enterprise Server

      Please reference the Installing Swarmia on GitHub Self-Hosted Enterprise Servers (On-Prem) article for detailed instruction. 

       

       

      Re-Installing Swarmia with GitHub

      You might need to reinstall the Swarmia GitHub app if you have previously uninstalled it for whatever reason. To do this, you first need to cancel your "plan" for the Swarmia app. Screenshots and guidance below. 

      To reinstall the app do the following:

      1. Navigate to the marketplace page at https://github.com/marketplace/swarmia
      2. Cancel your existing plan
      3. Setup a new plan for the app
      4. Login to Swarmia at https://swarmia.com/login

      Below is a screenshot showing the process:

      CleanShot 2023-01-27 at 13.21.30@2x

       

      Connecting Multiple GitHub Organizations

      Option 1: Multiple Swarmia organizations

      It is possible to sign up each of the GitHub organizations as completely separate Swarmia organizations and invite specific people to each of them.

      If a user with access to multiple organizations logs in to Swarmia, they can choose to which of the organizations they want to log in to. To switch organizations, the user needs to log out and back in.

      This approach is a good choice when:

      • There is a need to limit access control (all users don’t belong to all GitHub organizations and shouldn’t see data from orgs that they don’t belong to).
      • People mostly don’t work across multiple GitHub organizations. If they do, this approach is not optimal, as it will be difficult to get a full picture of a person's work due to being only able view it by one organization at a time.

      To use this approach, simply install the Swarmia app on each of your GitHub organizations. Then when you log in to Swarmia, you can choose which organization to log in. To invite team members to the organizations, send them the invite link that you can find from the bottom of the home page.

      Option 2: Syncing data from multiple GitHub organizations to a single Swarmia organization

      Alternatively, it is possible to sync data from multiple GitHub organizations to a single Swarmia organization, so that you can see all the data at once.

      This approach is a good choice when:

      • There are no internal access control concerns. Everyone from your company will see all data from all of your connected GitHub organizations.
      • Everyone in your company has access to all connected GitHub organizations. This is also enforced by Swarmia: if a user doesn’t have access to all of the organizations, we don’t allow them to login.
      • People are working across the GitHub organizations. With this approach, you can easily see a person’s work across all the organizations.

      Using this approach is easy, but currently requires some manual work from our engineering team. Please reach out to us at hello@swarmia.com or reach out to your CSM for support. We'll be happy to set it up for you. 

      Currently, it is not possible to combine data from a GitHub Cloud organization and a GitHub Enterprise Server organization. In that case, you should instead use Option 1.

       

      Maximizing GitHub Data

      To get the most from the GitHub integration, you may want to review the following articles to improve the relevance of the Pull Request Metrics that we gather from GitHub. 

       

      GitHub Data Access

      To review what data we request from GitHub you can review the resources below.

       

      Installation Troubleshooting

      If you encounter any issues during installation, we have articles in our FAQ that may be able to help.