FOSSA supports and integrates with GitHub tools out of the box.

FOSSA Supports two types of Github integrations, Oauth & Github app.

Once you decide on your authorization method of choice, you should be able to sign in with GitHub and immediately get going with importing repos and scanning Pull Requests, but some permission configurations can lead to access issues.

Choosing between OAuth and Github App

When a user navigates to Quick import they will see two different Github integration options.

• Github OAuth
• Github App

Please see the table below for a breakdown on the differences in the integration methods.

Overall if you as a user are comfortable with the permission scope required for Github OAuth then that integration method can be easier to scale, although presents challenges if the authorized user leaves your organization.

Alternatively Github App provides much more conservative and granular permission and repository scope, making this the preferred integration method for the majority of use-cases.

Integrating with GitHub Cloud (OAuth)

If you're in GitHub and not seeing repos or organizations listed, you may need to ensure that your account has the right permissions. Our integration functions as an OAuth App.

1. Ensure your account is added to the GitHub organization you're going to import from

Under https://github.com/orgs/{YOUR_ORG}/people the user should be listed in your organization. If not, make sure the user is added as a member with global read access.

2. Ensure your organization has granted access to FOSSA

a) First, revoke any existing FOSSA access at https://github.com/settings/applications.

b) Then, connect FOSSA back to GitHub at app.fossa.com/projects/import/github but DO NOT authorize yet; stop at this screen:

c) Ensure that your organization has access. You should see a green check mark:

If not, there should be a "Request" or "Grant" button that you need to click. You will need an administrator who is logged into that organization to grant access. They can configure third-party access settings at:

https://github.com/organizations/{YOUR_ORGANIZATION}/settings/oauth_application_policy

If you have turned on access restriction, ensure that FOSSA is approved:

If you already authorized the FOSSA app without also granting our app access to an organization with repositories that you want analyzed, you can still do so by logging in to your own GitHub account and navigating to the Authorized OAuth Apps page:

After you click on the FOSSA app, you'll see your organization near the bottom:

Click "Request" and have an owner of the organization approve the request. You'll then be able to import repositories owned by the organization.

Configuring GitHub Enterprise (OAuth)

📘

GitHub Enterprise (on-prem only)

This guide covers integrating an on-prem FOSSA appliance with GitHub Enterprise behind the firewall.

Configuring your Github Enterprise Instance

To get started, you will have to set up an Oauth App in GitHub. This can be done by navigating to `{GITHUB_URL}/organizations/{ORGANIZATION_NAME}/settings/applications:

Make sure you configure your Authorization callback URL to point to {FOSSA HOST}/api/services/github/authorize/callback

Configuring FOSSA (OAuth)

Now that GitHub Enterprise is configured, you will have to add access details to the FOSSA config. SSH into the box hosting FOSSA and edit FOSSA's configuration file (config.env). Find or add the following lines:

github__enabled=true
github__base_url={GITHUB_HOST}
github__enterprise=true

github__credentials__oauth2__client_id={GITHUB_CLIENT_ID}
github__credentials__oauth2__client_secret={GITHUB_CLIENT_SECRET}
github__credentials__oauth2__callback={FOSSA HOST}/api/services/github/authorize/callback

Restart FOSSA (OAuth)

If FOSSA is currently running, run fossa restart while still inside of your SSH session and wait for FOSSA to boot up again.

Congrats! Now you should be able to connect to Github Enterprise and begin importing from the service.