Dependabot Merge

Dependabot Merge

Merge safe dependency updates. Stop and report the unsafe ones. Never merge a pull request that you did not check in this run.

Use the gh-cli skill for queries, required-check watching, and failure logs. In a batch, process other ready pull requests instead of waiting on one.

The checks are the same for every dependency bot. Only the discovery query and the place that holds the update metadata change. See "Which bots".

Scope

The argument can name more than one owner, and can mix them, for example org goreleaser and user caarlos0. Without an argument, use the current user:

gh api user -q .login

Never widen the scope on your own. A user belongs to many organizations that they do not maintain. Merging there affects other people. List them:

gh api user/orgs --jq '.[].login'

Then ask which ones to process, and default to the owners the user clearly controls. Do not merge in a shared community organization without a clear yes.

Ledger

Keep a ledger, so that a second run does not check the same pull request again. Create it once per run with the sql tool:

CREATE TABLE IF NOT EXISTS dependabot_prs (
  url TEXT PRIMARY KEY,
  repo TEXT, number INTEGER, title TEXT,
  bot TEXT,       -- dependabot | renovate | pre-commit-ci | ...
  state TEXT,     -- pending | merged | skipped | blocked | failed
  reason TEXT,
  checked_at TEXT
);

Write a row with state='pending' when you find a pull request. Update the row immediately after each decision. Read the ledger before each step and process only pending rows. Report the terminal rows again at the end, but do not check them again.

Which bots

Handle every dependency bot, not only Dependabot. They differ in three ways: the author login, where the update metadata lives, and the branch prefix.

Renovate has no commit metadata block. Its versions live in a markdown table in the pull request body, next to a <!--renovate-debug:...--> comment:

gh pr view NUMBER -R REPO --json body -q .body

That table is generated at the same time as the diff, but it is still a summary. The rule below does not change: read the diff.

Two Renovate-only things to watch:

• A pull request that edits renovate.json, .github/renovate.json or .renovate.json is a configuration change, not a dependency bump. It is outside the manifest/lockfile/workflow allowlist, so it is blocked for a human.
• Renovate can run postUpgradeTasks and custom managers, so it can touch files a version bump does not explain. Treat any such file as a block.

Collect

gh search prs takes only one --author, and a second flag silently replaces the first. To cover several bots in one query, use the search API, where a repeated author: qualifier means OR:

gh api -X GET search/issues -f per_page=100 \
  -f q='is:pr is:open draft:false org:OWNER author:app/dependabot author:app/renovate' \
  --jq '.items[] | "\(.user.login)\t\(.html_url)\t\(.title)"'

Keep the q value on one line. A newline inside it makes the search API reject the whole query with 422 Validation Failed.

Use user:OWNER instead of org:OWNER for a personal account, and repeat the qualifier to cover both. Add any self-hosted bot with a plain author:renovate-bot (no app/ prefix, because it is a normal account).

Do not trust is_bot. In gh search prs output, dependabot[bot] reports is_bot: false. Match on the login instead.

Insert the results into the ledger, recording which bot opened each one.

Use single quotes for every SQL string. SQLite rejects a double-quoted literal that does not name a column, and the whole insert fails.

Fetch the facts for all of them in parallel, then triage from one table instead of one round trip per pull request. Write the worker to a file: on macOS, xargs -I combined with -n 1 and a long inline sh -c fails with command line cannot be assembled, too long.

cat > fetch.sh <<'EOF'
#!/bin/sh
gh pr view "$1" --json number,url,author,isDraft,mergeable,mergeStateStatus,\
files,commits,statusCheckRollup > "out/$(echo "$1" | tr '/:' '__').json" 2>&1
EOF
chmod +x fetch.sh
xargs -P 8 -I{} ./fetch.sh {} < urls.txt

Check each pull request

Get the facts in one call:

gh pr view URL --json number,author,isDraft,mergeable,mergeStateStatus,\
reviewDecision,files,commits,statusCheckRollup

The commit body holds the metadata in the updated-dependencies: block: dependency-name, dependency-version, dependency-type, and update-type. A grouped update lists many entries. Check every entry. Renovate puts the same information in the pull request body instead — see "Which bots".

The metadata can disagree with the diff. The diff wins. The bot rebases and the summary goes stale. One pull request declared dependency-version: 5.24.0 and update-type: version-update:semver-minor while gh pr diff showed 5.22.0 to 6.0.0. Another declared dependency-version: 10.0.1 while the workflow comment still read # v6.6.1 and the real old pin was v8.2.0 — three different answers, and only the diff was right. Read the diff before you call a bump minor:

gh pr diff NUMBER -R REPO -- package.json go.mod

For a pinned action, the comment after the SHA is decoration and can be stale. Resolve the SHA itself:

gh api repos/OWNER/REPO/tags --paginate \
  --jq '.[] | select(.commit.sha=="NEWSHA") | .name'

Set state='blocked' and continue to the next pull request if any of these is true:

• the author is not the expected bot, or a commit has a different author;
• mergeable is CONFLICTING;
• a required check failed — see "Which checks matter";
• the diff changes a file that is not a manifest, a lockfile, or a workflow (lockfiles include uv.lock, flake.lock, Cargo.lock, pnpm-lock.yaml), or it changes the bot's own configuration;
• the new version is less than 3 days old, or the release notes and the tag do not exist upstream;
• the package repository, the homepage, or the maintainer set changed;
• a lockfile adds a package with an install script (preinstall, postinstall, prepare).

A version-update:semver-major is not an automatic block. See "Major updates".

For an npm bump, compare the maintainer set of both versions, not only the new one:

for v in OLD NEW; do
  curl -s "https://registry.npmjs.org/PKG/$v" | jq -c '[.maintainers[].name]'
done

A set that shrinks inside the bump window is a block. axios went from 4 maintainers to 1 between 1.13.6 and 1.18.0, which concentrates publish rights on one account.

Which checks matter

Separate required failures from advisory ones. mergeStateStatus is an initial signal, not a complete check result:

Use gh pr checks NUMBER -R REPO --required to identify required checks. If the required set is unclear, confirm with protection and rulesets for the pull request's actual base branch, not necessarily the default branch:

base=$(gh pr view NUMBER -R REPO --json baseRefName --jq '.baseRefName | @uri')
gh api "repos/REPO/branches/$base/protection" --jq '.required_status_checks.contexts'
gh api "repos/REPO/rules/branches/$base" \
  --jq '[.[]|select(.type=="required_status_checks")
        |.parameters.required_status_checks[].context]'

404 Branch not protected and an empty ruleset list mean nothing is required. A 403 means you cannot read the rules. If the required set cannot be established, report it as unknown and block rather than infer passing CI.

Check isArchived first. You cannot merge into an archived repository, and GitHub reports it as BLOCKED with no protection and no rules, which looks like a required check:

gh repo view REPO --json isArchived,archivedAt

Report an archived repository as skipped, not as a CI failure.

Major updates

A major bump is a question, not a verdict: does the breaking change reach this project? Ask the deep-check subagent to state the documented breaking change in one sentence, then test it against the repository.

The evidence is the pull request's own CI. A green build on the pull request proves the new version works there, because the workflow ran with the bump applied. actions/checkout v7 only blocks fork checkout under pull_request_target and workflow_run, so this settles it:

for f in $(gh api repos/REPO/contents/.github/workflows --jq '.[].name'); do
  gh api "repos/REPO/contents/.github/workflows/$f" --jq .content | base64 -d \
    | grep -qE '^\s*(pull_request_target|workflow_run)\s*:' && echo "$f"
done

Merge when the breaking change cannot reach the project and CI is green. Block when it can, and name the mechanism.

A red check is not proof that the bump broke it

Compare against the base branch before you blame the bump:

gh run list -R REPO --limit 6 \
  --json conclusion,workflowName,headBranch,createdAt

Then read the log and name the error:

gh api --allow-escape-sequences repos/REPO/actions/jobs/JOB_ID/logs \
  | perl -pe 's/^.*?\dZ //' | perl -pe 's/(\e|\^\[)\[[0-9;]*m//g' \
  | grep -iE 'error|failed' | head -20

Two examples from one run. A snapshot job failed with an OpenCV aruco C++ compile error that also failed on master — unrelated, so the bump merged. A test job failed with npm ERESOLVE, because @typescript-eslint/eslint-plugin@8.65.0 needs typescript <7 through ts-api-utils — caused by the bump, so it stayed blocked.

HTTP 410 means the log expired. That is unknown, so it is blocked.

Query the advisory database for both versions, not only the new one:

gh api '/advisories?ecosystem=ECOSYSTEM&affects=NAME@VERSION&per_page=5' \
  --jq '.[] | {ghsa_id, severity, summary}'

An open advisory that affects the new version blocks the merge. An advisory that the bump repairs is a reason to merge — name the GHSA in the report, because it tells the maintainer which merges are urgent.

An upgrade is not automatically a fix. Check that the new version is outside the vulnerable range, not merely newer. golang.org/x/image 0.20.0 to 0.38.0 looked like a big catch-up, but GHSA-q675-qj96-32m9 is patched only in 0.41.0, so the bump landed still vulnerable. Block, and say which version would actually close it.

A check that fails everywhere is one broken tool

Before blaming any bump, ask whether the same check fails in unrelated repositories. If it does, it is a broken tool, and it is one problem rather than many. A ruleguard / scan job failed on seven pull requests across four repositories with internal error: package "context" without types, because the workflow installs it with go install ...@latest against a newer Go. It even failed on a pull request that only edited YAML, which the linter never reads — proof on its own that no bump caused it.

Two signals that a red check is not the bump's fault:

• the same failure appears on the base branch;
• the failing job cannot read any file the diff touched.

Ask the user whether a recurring failure is known-broken, and once they say it is, stop re-deriving it in later runs.

Deep check

A version number proves nothing about the content. Read the upstream diff for every bump that is not a patch of a dependency that you already trust, and for every npm or pypi bump.

Send this work to parallel subagents, one subagent for each dependency. Give each subagent the dependency name, both versions, and the compare URL:

https://github.com/OWNER/REPO/compare/vOLD...vNEW

Batch several dependencies into one subagent when they share an ecosystem. Ten subagents for ten dependencies wastes time; three grouped subagents do not.

Ask the subagent to report only evidence, with file and line references:

• obfuscated code, long base64 or hex strings, or a new minified file;
• new network calls, new subprocess calls, or new file-system writes;
• reads of environment variables, tokens, keys, or wallet paths;
• a new install script, or a new build step that downloads code;
• a change of maintainer, of signing key, or of the release workflow;
• a diff that is much larger than the version bump promises.

For a major bump, also ask for the documented breaking change in one sentence. You need it for the impact test above.

Tell the subagent that a minified dist/ bundle is normal in a GitHub Action. Only a bundle change that does not match the source change in the same diff is evidence. That rule found a real one: svenstaro/upload-release-action 2.11.5 changed dist/index.js by +37822/-33780 with no source change, and also shipped the maintainer's .claude/settings.local.json in the release tag.

The subagent reports clean, suspicious, or unknown. Treat suspicious and unknown as blocked. A compare page that does not exist is blocked, because the tag does not match the release.

One suspicious entry blocks the whole grouped pull request, even when the other entries are clean.

Comment on the pull request

When a pull request is blocked for anything a reader would call suspicious, post the evidence as a comment on that pull request, then leave it open. The finding belongs where the next person will look, not only in the report.

Comment for a supply-chain finding: a maintainer set that shrank, a repository that moved, a bundle that does not match its source, an unexplained file in a release tag, an advisory the bump fails to close, or a version published inside the cool-down. A plain red test or a merge conflict does not need a comment.

Write the comment so it stands on its own:

• name the finding in the first line, and say the pull request was not merged;
• show the evidence, with the exact numbers or the two version strings;
• say what is not wrong, so nobody re-does the work — for example that the maintainer who remains is the long-standing lead, or that a large bundle diff is explained by an ESM migration in the same commit;
• give the smallest action that unblocks it, such as splitting one dependency out of a group or targeting a later patch version;
• if the blocked bump also fixes advisories, say so, so it is not left to rot.

Markdown bodies with backticks break shell heredocs. Write the body to a file first, then:

gh pr comment NUMBER -R REPO --body-file comment.md

Merge

Merge only a pull request that passed every check above. A red check is acceptable only when it is not required and you showed that the bump did not cause it.

Use the method that the repository permits:

gh repo view REPO --json squashMergeAllowed,mergeCommitAllowed
gh pr merge NUMBER -R REPO --squash --delete-branch

Prefer squash. Use --merge when squash is not permitted. Never rebase.

--delete-branch fails with Cannot use -d or --delete-branch when merge queue enabled. Drop the flag for those repositories.

--auto is only useful when the repository has allow_auto_merge. Otherwise it merges at once:

gh api repos/REPO --jq .allow_auto_merge

gh pr merge prints nothing when it succeeds, and it can fail silently in a loop. Always verify:

gh pr view NUMBER -R REPO --json state,mergedAt

Base branch was modified means the bot replaced the pull request while you worked. Dependabot closes the old one with "Looks like these dependencies are updatable in another way"; Renovate silently force-pushes the same branch instead. Find the replacement, record the old row as skipped, and check the new pull request from the start:

gh pr list -R REPO --author app/dependabot --state open --json number,title

Update the ledger after every merge. A failed merge is state='failed' with the error text as the reason.

Watch what your own merges did. A merged bump can break the default branch even when the pull request was green, because a workflow may not run on pull requests at all. After a batch, check the default branch, and establish whether a red run predates the merge before claiming either way:

gh run list -R REPO --branch "$(gh api repos/REPO --jq .default_branch)" \
  --limit 6 --json conclusion,workflowName,createdAt

A run with 0 jobs and "workflow file issue" is a broken workflow file or an unreachable reusable workflow, not a dependency problem.

Report

One line for each pull request, grouped by result:

• Merged — repository, dependency, and version change. Mark the ones that close an advisory, and name the GHSA.
• Blocked — the single reason, and the evidence for it.
• Skipped — an archived repository, or a superseded pull request.
• Failed — the error.

Group the blocked ones by cause, so that one broken workflow does not look like ten bad dependencies. Four pull requests that all fail ruleguard / scan are one problem.

Close with the count for each group, and the pull requests that need a human. Name the suspicious dependency first, and call out any blocked pull request that is holding back a security fix, because those must not sit forever.

Expect to be asked "what is left?" — every blocked row needs a reason a person can act on, not just a status.

Gotchas

• gh repo view --json defaultBranch is not a field. Use defaultBranchRef, or gh api repos/REPO --jq .default_branch.
• A 403 from the rules API does not prove there are no required checks. See "Which checks matter" before making a merge decision.
• On a private repository the only pull-request check may be a linter while the real build never runs there. Weak signal — say so rather than implying the bump was proven safe.
• HTTP 410 on a job log means it expired. That is unknown, so blocked.
• Merging one pull request can make a sibling in the same repository conflict. Merge, then re-poll the rest instead of trusting the earlier snapshot.