merge-dependabot

name	merge-dependabot
description	Review, fix, validate, and merge every open Dependabot pull request without breaking the application.

Codex invocation: use $merge-dependabot or select this skill through /skills. References below to /merge-dependabot describe the source repository command.

Use this command when all open Dependabot pull requests should be brought to green and merged safely.

The expected result is that every Dependabot pull request is merged after its checks pass, with compatibility fixes included when dependency changes affect the repository.

Input

/merge-dependabot does not take arguments.

If arguments are provided, report that they are ignored and process every open Dependabot pull request in the current repository.

Preconditions

Before changing branches or merging pull requests, verify that:

• the current directory belongs to the intended Git repository;
• the GitHub repository and default branch can be identified;
• GitHub authentication permits reading checks, pushing PR branches, and merging pull requests;
• the working tree is clean, with no staged, unstaged, or untracked changes;
• no merge, rebase, cherry-pick, revert, or bisect operation is in progress.

Record the starting branch so it can be restored at the end. If a precondition is not met, report it and stop.

After changing branches, attempt to restore the starting branch before every exit, including success, failure, interruption, and user-decision exits. Restoration means checking out the recorded branch without pulling, merging, rebasing, resetting, fast-forwarding, rewriting, or otherwise mutating its ref unless the user explicitly requests that change. If restoration cannot be completed safely, leave all refs unchanged and report the exact blocker.

This command is authorized to commit and push focused compatibility fixes to Dependabot PR branches and to merge Dependabot PRs after all required checks pass.

Workflow

1. Fetch the default branch and list every open pull request authored by dependabot[bot], including PR number, title, dependency, version change, target branch, changed files, mergeability, and check results.
2. If no Dependabot PR is open, restore the starting branch, report that no work was needed, and stop.
3. Process PRs one at a time because dependency PRs commonly modify the same lockfile and each merge can make the remaining branches stale or conflicting.
4. Prefer low-risk patch and minor updates with green checks before major or failing updates. Re-query all remaining PRs after every merge.
5. For a mergeable PR whose required checks are complete and successful:
   • review its dependency scope and changed files for unexpected changes;
   • merge it with a repository-enabled merge method;
   • never bypass a failed or pending required check;
   • fetch the updated target branch before processing the next PR.
6. When a PR conflicts with its target branch, request a Dependabot rebase first and wait for the branch and checks to update. If Dependabot cannot resolve the conflict, check out the PR branch, integrate the latest target branch, resolve package manifests before regenerating the lockfile with pnpm, validate the result, and push the focused resolution.
7. For every failed check, inspect the complete failing job logs and classify the failure as one of:
   • dependency incompatibility or application regression;
   • deterministic repository or CI issue exposed by the update;
   • unrelated transient infrastructure failure;
   • known flaky test with evidence in the failure output or surrounding runs.
8. Retry only failures supported by evidence as transient or flaky. Do not repeatedly rerun an unexplained failure and do not merge while any required check remains red.
9. For dependency incompatibilities or regressions:
   • read relevant repository guidance under docs/**;
   • inspect the dependency's official migration guide, release notes, and current version-specific documentation using Context7 or another authoritative source;
   • identify breaking changes that affect the repository's actual APIs, configuration, runtime, build, or tests;
   • implement the smallest compatibility change that preserves documented application behavior;
   • add or update tests when behavior or a reusable technical contract changes;
   • update documentation according to AGENTS.md and docs/how-to/documentation-writing-standards.md.
10. Validate fixes locally with pnpm install --frozen-lockfile, pnpm lint:fix, pnpm lint, pnpm typecheck, the affected test suites, and affected builds or packaging commands. Use docs/how-to/pre-merge-change-validation.md to expand validation when risk crosses multiple boundaries.
11. Before committing a compatibility fix, inspect git status, the focused diff, and recent commits. Commit only intended files with a concise repository-style message, push to the Dependabot PR branch, and verify that a new CI run starts for the pushed commit.
12. Wait for all required checks on the corrected PR head commit. If a check fails, return to the failure-classification step until the PR is green or a safe resolution requires a user decision.
13. Merge the corrected PR only after all required checks pass. Never force-merge a red PR or weaken tests, application behavior, security controls, or quality gates merely to obtain green checks.
14. Continue until a fresh GitHub query reports no open Dependabot pull requests.
15. Fetch the final default branch, then restore the starting branch without updating its ref. If restoration cannot be completed safely, leave all refs unchanged and report the exact blocker.
16. Report the result.

Required output

Report:

• repository and target branch;
• every Dependabot PR found, with dependency and version change;
• check failures investigated and their root causes;
• official migration or release documentation consulted for breaking changes;
• compatibility fixes, tests, and documentation changes made;
• local validation commands and results;
• every merged PR with its URL and merge result;
• any PR not merged, with the exact blocker;
• final count of open Dependabot PRs;
• restored branch and final status.