General

Core Settings

Fossa has three config levels: Global, Repository, and Directory. Learn how they work in Config Inheritance & Overrides.

Config Priority

You can keep your review configuration in a fossa-config.yml file at the root of your repository instead of the web UI.

The file is ignored until you opt in. By default fossaConfigFileOverridesWebPreferences is false, which means Fossy never reads fossa-config.yml — committing the file alone does nothing.Turn it on first in Settings → Code Review → the repository → General, or set fossaConfigFileOverridesWebPreferences: true at the repository (or directory) level in the web UI. Only then does the file take effect.

Once enabled, the file is merged on top of your web settings, so you only need to declare the keys you want to change — anything you omit keeps its web value.

Unknown keys are silently dropped. Any top-level key that isn’t part of the current schema is removed before the config is applied — no error, no warning. If a setting appears to have no effect, check the spelling against the sample below.

Sample fossa-config.yml

version: 2.0

# general
automatedReviewActive: true
showStatusFeedback: true
fossaConfigFileOverridesWebPreferences: false
reviewCadence:
    type: 'automatic' # automatic | auto_pause | manual
    timeWindow: 15 # minutes
    pushesToTrigger: 3
pullRequestApprovalActive: false
isRequestChangesActive: false # not available on GitLab
runOnDraft: true
ignorePaths:
    - 'yarn.lock'
    - 'package-lock.json'
    - 'package.json'
    - '.env'
    - '**/*.json'
ignoredTitleKeywords: []
baseBranches: []
enableCommittableSuggestions: true
byokModel: '' # empty = inherit the model from your BYOK settings

# Sibling repos the agent may consult during review.
# Soft cap of 3; empty = feature off.
linkedRepositories: []

# review categories
reviewOptions:
    bug: true
    performance: true
    security: true
    business_logic: true

# suggestion control
suggestionControl:
    applyFiltersToFossyRules: false
    severityLevelFilter: 'medium' # low | medium | high | critical

# PR summary
summary:
    generatePRSummary: true
    behaviourForNewCommits: 'none'
    behaviourForExistingDescription: 'replace'
    customInstructions: ''

# fossy rules
ideRulesSyncEnabled: false
fossyRulesGeneratorEnabled: true
fossyLearningExcludedReviewers: []
fossyKnowledgeApproval:
    enabled: false

# custom messages
customMessages:
    globalSettings:
        hideComments: false # GitHub only
        suggestionCopyPrompt: true # not available on Bitbucket
    errorReviewMessage:
        status: 'off' # off | active
        content: ''
    startReviewMessage:
        status: 'every_push' # every_push | only_when_opened | off
        content: ''
    endReviewMessage:
        status: 'every_push' # every_push | only_when_opened | off
        content: ''

This sample mirrors the shipped defaults. The canonical source is default-fossa-config.yml in the fossa-ai repository.

Review Behavior

Automated Review

Fossy can review PRs automatically when opened, or only when you comment @fossy start-review.

This affects the initial review only. For subsequent commits, see Review Cadence below.

Review Cadence

How Fossy handles reviews on subsequent commits:

Automatic
Auto-pause
Manual

Review every new push. Continuous feedback on all changes.

Only run follow-up reviews when you comment @fossy start-review.

PR Workflow

Auto-approve PRs

Fossy approves PRs when no issues are found. Platforms: GitHub, GitLab, Bitbucket

Request Changes

Fossy requests changes when finding critical issues. Platforms: GitHub, Bitbucket

Skip Conditions

Ignored Files: Use glob patterns (e.g., **/*.js), one per line. Default: yarn.lock, package-lock.json, package.json, .env, **/*.json Ignored Titles: Skip PRs with specific keywords (case-insensitive, max 100 chars) Base Branches: Restricts which base branches get reviewed.

Empty (the default) means every base branch is reviewed — there is no built-in dev/release/master list. Add entries only when you want to narrow the scope: once the list is non-empty, Fossy reviews only PRs targeting those branches (your repository’s default branch is always included).Entries are matched against the PR’s target branch and support a small pattern syntax:

Entry	Matches
`main`	PRs targeting exactly `main`
`release/*`	PRs targeting any branch under `release/` (`*` is a single-level wildcard)
`=main`	Exact match, same as writing `main`
`!staging`	Excludes PRs targeting `staging`
`contains:hotfix`	Matches on the source branch instead — any PR whose head branch contains `hotfix`

When several entries match, the most specific one wins. Each entry is limited to 100 characters, may only use a-z A-Z 0-9 / * - _ ! = :, and ** is not allowed.

Draft PRs: runOnDraft is true by default, so drafts are reviewed. Set it to false to skip them until the PR is marked ready.

Analysis Types

Fossy reviews across four categories. Enable or disable each one under Analysis Types, or via reviewOptions in fossa-config.yml.

Bug — logic errors, race conditions, null dereferences, edge cases, and incorrect behavior.
Security — vulnerabilities, injection, auth issues, data exposure, and secrets.
Performance — N+1 queries, hot-path allocations, missing caching, and blocking I/O.
Business Logic — validates the implementation against business rules, requirements, and acceptance criteria linked in the PR. See Business Logic Validation.

Fossy Rules are not one of these categories — they always run, independently of reviewOptions. See Fossy Rules.

Getting Started

Open Source & BYOK

AI Code Review

CLI

Cockpit

Fossy Issues

Organization

Security

Troubleshooting

Core Settings

Config Priority

Review Behavior

Automated Review

Review Cadence

PR Workflow

Auto-approve PRs

Request Changes

Skip Conditions

Analysis Types

​Core Settings

​Config Priority

​Review Behavior

​Automated Review

​Review Cadence

​PR Workflow

​Auto-approve PRs

​Request Changes

​Skip Conditions

​Analysis Types

Core Settings

Config Priority

Review Behavior

Automated Review

Review Cadence

PR Workflow

Auto-approve PRs

Request Changes

Skip Conditions

Analysis Types