> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dependency Management

<Badge text="development" color="orange" />

## 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`](https://github.com/amd/gaia/blob/main/.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](https://github.com/amd/gaia/issues/1157)).

A companion workflow at [`.github/workflows/dependabot-automerge.yml`](https://github.com/amd/gaia/blob/main/.github/workflows/dependabot-automerge.yml) auto-merges low-risk Dependabot PRs once required status checks pass.

## Current configuration

| Directory                                                  | Ecosystem      | Limit | Group                        | Schedule        |
| ---------------------------------------------------------- | -------------- | ----- | ---------------------------- | --------------- |
| `/`                                                        | pip            | 5     | `python-dependencies`        | weekly / monday |
| `/`                                                        | npm            | 5     | `root-npm-dependencies`      | weekly / monday |
| `/src/gaia/apps/webui`                                     | npm            | 5     | `agent-ui-dependencies`      | weekly / monday |
| `/src/gaia/apps/example/webui`                             | npm            | 5     | `example-app-dependencies`   | weekly / monday |
| `/src/gaia/apps/jira/webui`                                | npm            | 5     | `jira-app-dependencies`      | weekly / monday |
| `/hub/agents/python/emr/gaia_agent_emr/dashboard/electron` | npm            | 5     | `emr-dashboard-dependencies` | weekly / monday |
| `/`                                                        | github-actions | 5     | `github-actions`             | weekly / monday |

**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`:

   ```yaml theme={null}
     - 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](https://github.com/amd/gaia/issues/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`](https://github.com/amd/gaia/blob/main/.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](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) 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`](https://github.com/amd/gaia/blob/main/.github/dependabot.yml) — authoritative config
* [`.github/workflows/dependabot-automerge.yml`](https://github.com/amd/gaia/blob/main/.github/workflows/dependabot-automerge.yml) — the auto-merge workflow
* [`util/check_dependabot.py`](https://github.com/amd/gaia/blob/main/util/check_dependabot.py) — regression linter wired into `python util/lint.py --all`
* [Dependabot documentation](https://docs.github.com/en/code-security/dependabot) — official GitHub docs

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>