Configuration reference

Excubia reads one optional file, excubia.json, at the root of the scanned project (or the file passed with --config), and a few environment variables. Without the file every default below applies.

• The file is JSON so it works without booting Laravel and is easy for agents to edit. JSON Schema: excubia.schema.json. Add "$schema" to get completion in your editor.
• Unknown keys, wrong types and out-of-range values are a configuration error: the command prints which key and exits 2.
• In a Laravel app the service provider reads the default excubia.json of the app base path once per boot. An invalid file there disables the opt-in features (the app still boots); php artisan excubia:check shows the error.
• Command-line options win over the file: --fail-on over failOn, --no-dev over includeDev. --strict can only turn strict on.

Full example

Every key with its default value, except $schema, ignore and app, which have no default:

{
  "$schema": "https://raw.githubusercontent.com/qiick-io/excubia-core/main/excubia.schema.json",
  "failOn": "high",
  "includeDev": true,
  "strict": false,
  "checks": {
    "composer-stale": { "staleAfterMonths": 24 },
    "php-eol": { "warnDaysBeforeEol": 180 },
    "laravel-eol": { "warnDaysBeforeEol": 180 },
    "node-eol": { "enabled": true },
    "laravel-scheduler-heartbeat": { "staleAfterMinutes": 10 },
    "laravel-failed-jobs": { "highSeverityAfterHours": 24 }
  },
  "ignore": [
    {
      "checkId": "composer-advisories",
      "subject": "vendor/package",
      "advisoryId": "GHSA-xxxx-xxxx-xxxx",
      "reason": "Not reachable from our code",
      "until": "2027-01-31"
    }
  ],
  "cache": { "directory": null, "ttlHours": 24 },
  "privacy": { "skipPackages": [] },
  "app": { "url": "https://excubia.example.com" },
  "healthEndpoint": { "enabled": false, "path": "excubia/health" },
  "runtime": {
    "enabled": false,
    "bufferMaxBytes": 1048576,
    "requests": { "enabled": true, "sampleRate": 1 },
    "slowQueries": { "enabled": true, "sampleRate": 1, "thresholdMs": 1000 },
    "jobs": { "enabled": true, "sampleRate": 1 },
    "scheduler": { "enabled": true, "sampleRate": 1 },
    "outgoingHttp": { "enabled": true, "sampleRate": 1 }
  },
  "exceptions": {
    "enabled": false,
    "maskPatterns": [],
    "ignore": [],
    "bufferMaxBytes": 1048576
  }
}

General

Checks

checks holds per-check settings. Only these checks have settings; any other check id here is an error. To turn a check off, use --skip (or node-eol.enabled).

Ignore rules

ignore is a list of findings you accept. A rule matches a finding with the same checkId and subject, and, when advisoryId is set, the same advisory. Ignored findings are removed from the report, the exit code and the health endpoint.

Response cache

Data-source responses are cached on disk so repeated runs and --offline work without network.

--no-cache bypasses the cache for one run. vendor/bin/excubia cache:clear deletes the cache entries (only files named like cache entries).

Privacy

Packages the lockfile shows as not served by Packagist or the public npm registry are never sent to a public data source; see private packages. privacy.skipPackages adds names the lockfile cannot tell apart, such as a private package published on the public npm registry.

excubia-app

The target of excubia push, excubia:push and excubia:push-runtime. See the push guide.

Health endpoint

See the health endpoint guide. The secret is not a key: it comes from EXCUBIA_HEALTH_SECRET only.

Runtime monitoring

See the runtime monitoring guide. Off by default; only runtime.enabled is needed to turn it on.

Exception capture

See the exception capture guide. Off by default and independent of runtime.

Environment variables

Excubia reads these from the process environment (getenv()), never from Laravel config. With php artisan config:cache, Laravel no longer loads .env into the process, so set them in the real environment: the PHP-FPM pool, the container, the systemd unit or the CI job.

Empty values count as unset.

Source: docs/guides/configuration.md in excubia-core.