Dependency Management

​

What is Dependabot?

Dependabot automatically monitors GAIA’s dependencies and opens pull requests for security and version updates. PRs that meet a strict low-risk gate (patch updates, or minor updates to development-only deps) auto-merge once CI is green; everything else waits for human review.

​

How GAIA uses Dependabot

Dependabot is configured in .github/dependabot.yml and runs every Monday across seven entries: one for Python (pip), one for GitHub Actions, and five for npm (the root workspace plus four standalone app workspaces). Every entry has open-pull-requests-limit: 5 — the prior 0 (soft-disabled) state was a “silent fallback” violation that’s now retired by design (#1157). A companion workflow at .github/workflows/dependabot-automerge.yml auto-merges low-risk Dependabot PRs once required status checks pass.

​

Current configuration

Why grouping matters. Each ecosystem uses a wildcard groups: stanza so that a week’s worth of updates collapse into a single grouped PR per ecosystem. Without grouping, the limit: 5 would be hit by five individual single-package PRs and the rest would queue — defeating the point of the cap. Workspace coverage. The root npm entry follows the workspaces declaration in package.json (src/gaia/electron, src/gaia/apps/*/webui). The flagship Agent UI at src/gaia/apps/webui is not matched by that glob (it sits directly under apps/, not under apps/<name>/webui) so it has its own entry above.

​

Auto-merge policy

The workflow at .github/workflows/dependabot-automerge.yml enrols a Dependabot PR in GitHub’s native auto-merge queue (gh pr merge --auto --squash) when all of the following are true:

• The PR author and the trigger actor are both dependabot[bot] (defense in depth).
• The fetched metadata’s dependency-type does not include indirect.
• The PR does not update dependabot/fetch-metadata itself.
• AND either:
  • update-type == version-update:semver-patch, OR
  • update-type == version-update:semver-minor AND dependency-type includes direct:development AND does NOT include direct:production.

GitHub then merges the PR only after required status checks pass — Code Quality (Lint) and Unit Tests (the merge-queue gates) plus any required ecosystem checks. If CI fails, GitHub cancels the merge and the PR stays open. What requires human review:

• Any major-version bump.
• Indirect (transitive) dependency bumps.
• Grouped PRs that mix production and development dependencies.
• Updates to dependabot/fetch-metadata (would auto-merge itself with contents: write — supply-chain risk).

​

Adding a new ecosystem entry

To track a new package.json root (e.g., a new app under src/gaia/apps/):

1. Add an entry to .github/dependabot.yml:
     - package-ecosystem: "npm"
       directory: "/src/gaia/apps/your-app/webui"
       schedule:
         interval: "weekly"
         day: "monday"
       labels:
         - "dependencies"
         - "javascript"
         # Add "electron" only if the app ships an Electron shell.
       open-pull-requests-limit: 5
       groups:
         your-app-dependencies:
           patterns:
             - "*"
   
2. Run python util/check_dependabot.py to validate. The script enforces two invariants (per #1157):
   • No entry has open-pull-requests-limit: 0.
   • Every npm entry has a groups: stanza.
3. Update this doc’s “Current configuration” table.

​

Configuration fields reference

• package-ecosystem: package manager type (npm, pip, github-actions).
• directory: path to the folder containing the manifest, relative to the repo root.
• schedule.interval + schedule.day: how often to check.
• labels: tags added to PRs for filtering. The repo’s dependencies and electron labels exist in .github/labeler.yml.
• open-pull-requests-limit: max concurrent open PRs. Use 5. Setting 0 soft-disables the entry and is rejected by util/check_dependabot.py.
• groups: required for npm entries. Combines related updates into a single grouped PR per cycle.

See the official Dependabot docs for the full schema.

​

Operational notes

• First Monday after re-enablement may be busy. The soft-disabled era accumulated months of skipped updates; the first batch will be larger than steady state (~6–8 grouped PRs across all ecosystems).
• Grouped PRs that mix prod + dev deps don’t auto-merge. This is by design — bundling a production patch with a dev minor is exactly the case a human should look at. Manually merge with gh pr merge --auto --squash <PR> after review if you want it enrolled in the queue.
• Pre-merge maintainer setting: “Allow auto-merge” AND “Allow squash merging” must both be enabled in repo Settings → General → Pull Requests. Without either, gh pr merge --auto --squash queues successfully but GitHub cancels the merge. Verify: gh api repos/amd/gaia --jq '{allow_auto_merge: .allow_auto_merge, allow_squash_merge: .allow_squash_merge}'.
• Diagnosing “why didn’t this PR auto-merge?”: the workflow logs dependency-names, dependency-type, and update-type for every run. Check the workflow run’s “Log metadata for debugging” step.

​

See also

• .github/dependabot.yml — authoritative config
• .github/workflows/dependabot-automerge.yml — the auto-merge workflow
• util/check_dependabot.py — regression linter wired into python util/lint.py --all
• Dependabot documentation — official GitHub docs

---