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 Cloud with Data Residency

GitHub Enterprise Cloud with Data Residency (GHEC-DR) instances require the app to be registered within your instance.

1. 1

   Open the GitHub app installer

   Log in to bot.fossa.com and go to Settings > Integrations > Install GitHub app.

2. 2

   Enter your instance URL

   Enter your custom *.ghe.com API server URL to complete the configuration.

Expand

GitHub Enterprise Server

GitHub Enterprise Server (GHES) instances also require the app to be registered within your instance. The flow matches GHEC-DR: log in to bot.fossa.com, go to Settings > Integrations > Install GitHub app, and enter your custom API server URL.

Expand

Required permissions

The fossabot GitHub App requests these permissions:

It subscribes to these events:

• Pull request
• Issue comment
• Pull request review
• Pull request review comment
• Pull request review thread

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:

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.