Setup

Overview

fossabot connects to your source host as a GitHub App or a GitLab integration. You install and manage it from the fossabot dashboard at bot.fossa.com.

Once a repository is connected, fossabot runs automatically on new pull or merge requests. You can also trigger it manually:

• GitHub: comment @fossabot analyze on the pull request.
• GitLab: comment /fossabot analyze on the merge request.

Connecting fossabot to GitHub

For repositories on github.com or GitHub Enterprise Cloud, install the GitHub App from bot.fossa.com. Your engineers keep viewing analysis and pull requests in GitHub. Each repository can be set to trigger fossabot automatically or manually.

GitHub Enterprise Server or Cloud Data Residency

GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud with Data Residency (GHEC-DR) require the GitHub App to be registered within your instance, so you create your own app and register its credentials with fossabot. The steps are the same for both. Only your instance URL differs (your GHES server host such as https://github.your-company.com, or your *.ghe.com tenant for GHEC-DR).

1. 1

   Start in fossabot

   Log in to bot.fossa.com, go to Settings > Integrations > Install GitHub app, expand Using GitHub Enterprise Server or Cloud Data Residency?, and enter your instance URL.

2. 2

   Create a GitHub App on your instance

   Create the app under the organization or enterprise that should own it:

   • Organization: https://<your-instance>/organizations/<your-org>/settings/apps/new
   • Enterprise: https://<your-instance>/enterprises/<your-enterprise>/settings/apps/new

   An enterprise-owned app can only be installed on organizations within that enterprise.

3. 3

   Configure the app

   Basic information

   • GitHub App name: fossabot (or any name; fossabot uses it for its @fossabot mentions)
   • Homepage URL: https://bot.fossa.com

   Identifying and authorizing users: add both Callback URLs, and leave Request user authorization (OAuth) during installation and Enable Device Flow unchecked:

   • https://bot.fossa.com/api/auth/callback/github
   • https://vcs.fossa.com/api/v1/connections/github/oauth/callback

   Post installation

   • Setup URL: https://vcs.fossa.com/api/v1/connections/github_app/app/callback
   • Leave Redirect on update unchecked.

   Webhook

   • Check Active and keep Enable SSL verification on.
   • Webhook URL: https://vcs.fossa.com/webhooks/github
   • Webhook secret: generate one (you'll paste it into fossabot in the next steps).

   Permissions and events: set them as listed under Required permissions below.

4. 4

   Generate credentials

   Generate a Client secret and a Private key (download the .pem file).

5. 5

   Register with fossabot

   Back in the Install GitHub app form, enter your App ID, App name (the slug from the app's URL), Client ID, Client Secret, Private Key (the contents of the .pem), and Webhook Secret, then select Register & Install.

6. 6

   Install and allowlist

   fossabot redirects you to your instance to install the app, then choose the repositories fossabot should access. Make sure your network allows fossabot to reach your instance and allows your instance to send webhooks to fossabot (see Network access).

Expand

Required permissions

The fossabot GitHub App requests these repository permissions:

One organization permission:

It subscribes to these events:

• Issues
• Issue comment
• Pull request
• Pull request review
• Pull request review comment
• Pull request review thread
• Push

Bulk onboarding of repos

If you have hundreds or thousands of repositories, onboard them in bulk with a scoped token instead of installing one repository at a time.

1. 1

   Generate a token

   Create a personal access token (classic) with the repo scope, using a GitHub account that has admin access to the target repositories. The PUT endpoint used below only works for a classic PAT (ghp_) with the repo scope; a fine-grained or user-to-server (ghu_) token is rejected with a 404.

2. 2

   Find your repository IDs

   Bulk onboarding uses numeric repository IDs (for example 1296269), not owner/name. List them with the GitHub CLI:

   Copy

   gh api --paginate /orgs/<ORG>/repos -q '.[] | "\(.id) \(.full_name)"'

3. 3

   Add each repository

   Using the scoped token, add each repository to the installation:

   Copy

   export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
   gh api --method PUT \
     /user/installations/<INSTALLATION_ID>/repositories/{REPO_ID}

Connecting fossabot to GitLab

For GitLab, cloud or self-managed, connect from bot.fossa.com using OAuth or a GitLab access token. Your engineers keep viewing analysis and merge requests in GitLab. Each repository can trigger fossabot automatically or manually with a /fossabot analyze comment or from the UI.

GitLab access token requirements

If you connect with an access token, it needs the following scopes.

Legacy scopes: api, read_repository, write_repository

Fine-grained scopes:

Network access

fossabot runs in FOSSA's cloud, not inside your network. If your firewall restricts traffic to your source host or package registries, allow the following. Source hosts need traffic in both directions; package registries only need inbound.

• Inbound to your network: fossabot connects to your GitHub Enterprise Server or self-managed GitLab instance to read repositories and open pull or merge requests. It also connects to any private registry or code mirror you configure. Allow inbound connections from FOSSA's public IP addresses, listed on IP Space Allowlisting.
• Outbound from your network: your source host sends webhook events to fossabot. For GitHub Enterprise Server, allow outbound HTTPS to vcs.fossa.com.

What's next

• fossabot for Dependency Upgrades: Configure how fossabot proposes and fixes upgrades.
• Supported Ecosystems & Tools: Confirm your languages are covered and configure private registries.