GitHub App

Overview

The FOSSA GitHub App provides more conservative and granular permissions than OAuth: access is tied to an app installation rather than an individual user account, so it survives team changes. You can scope it to all repositories or a selected subset.

How it works

When an organization installs the FOSSA GitHub App, GitHub generates an installation access token that FOSSA uses to read code, post commit statuses, and manage pull request checks. Webhooks notify FOSSA of new pushes and PR events automatically, with no per-project webhook setup required.

Required permissions

Configure the following when creating the GitHub App in GitHub. The Minimum column is what FOSSA requires for core functionality; permissions marked N/A are not used.

Repository permissions

Organization permissions

No organization permissions are required. All organization-level permissions should be set to N/A.

Installing on GitHub Cloud

For FOSSA Cloud, the app is already registered; users just need to install it on their organization.

1. 1

   Start the installation

   In FOSSA, go to Add Projects → Quick Import → GitHub App. FOSSA will redirect you to the GitHub App installation page.

   Alternatively, navigate directly to https://github.com/apps/{FOSSA_APP_NAME}/installations/new.

2. 2

   Select repositories

   Choose All repositories to give FOSSA access to all current and future repos, or Only select repositories to scope access to specific ones. Click Install.

3. 3

   Import projects

   Return to FOSSA's Add Projects page. Your repositories will now appear under the GitHub App import option.

Setting up on On-Prem

Creating the GitHub App in GitHub

1. 1

   Register a new GitHub App

   In GitHub, navigate to Settings → Developer settings → GitHub Apps → New GitHub App (for personal accounts), or Organization Settings → Developer settings → GitHub Apps (for org-owned apps).

   Fill in the following:

   • GitHub App name: choose a name (this becomes the app slug used in install URLs)
   • Homepage URL: your FOSSA instance URL (e.g., https://fossa.yourcompany.com)
   • Webhook URL: {FOSSA_HOST}/api/services/github-app/webhook
   • Webhook secret: generate a strong random string and note it
2. 2

   Set repository permissions

   Under Repository permissions, configure exactly the values from the required permissions table above. Leave all organization permissions as N/A.

3. 3

   Subscribe to events

   Under Subscribe to events, enable:

   • Push
   • Pull request
   • Installation (to track installs and uninstalls)
4. 4

   Generate a private key

   After saving the app, scroll to the bottom of the app settings page and click Generate a private key. GitHub downloads a .pem file; keep this secure.

   Also note the App ID shown at the top of the app settings page, and the Client ID and Client Secret under OAuth credentials.

Configuring FOSSA

SSH into the FOSSA appliance and edit config.env. Add or update the following:

github_app__enabled=truegithub_app__base_url={GITHUB_HOST}github_app__app_id={APP_ID}github_app__app_name={APP_SLUG} github_app__credentials__oauth2__client_id={CLIENT_ID}github_app__credentials__oauth2__client_secret={CLIENT_SECRET}github_app__credentials__webhook_secret={WEBHOOK_SECRET}github_app__credentials__private_key={PEM_CONTENT}

For github_app__credentials__private_key, paste the full contents of the .pem file downloaded in the previous step.

Then restart FOSSA:

fossa restart

Installing the app

Once FOSSA is restarted, users install the app by visiting:

https://{GITHUB_HOST}/apps/{APP_SLUG}/installations/new

Or from within FOSSA: Add Projects → Quick Import → GitHub App.

Reference: config keys