A Dependency-Update Bot with Renovate: Config, Grouping, CI, and Failure Modes 2026

Contents

Manual dependency maintenance drifts into stale lockfiles and a stream of single-package pull requests that compete for review time. Renovate can group those updates, schedule them, and automerge the low-risk ones. This guide walks through the four parts of a working setup: config discovery, a baseline config, CI wiring with the official GitHub Action, and the failure modes the official documentation describes.

How This Guide Was Built

This guide is assembled from the official Renovate configuration options, the running Renovate guide, the automerge documentation, and the GitHub Action README. The published renovate-schema.json supports editor validation. Every config key and behavior below is taken from those pages. This guide is assembled from official documentation and community reports — we did not run this build ourselves.

Where Renovate Reads Its Config

Renovate reads its repository config only from the default branch, checking a fixed list of file names in order. The first match wins.

Renovate checks renovate.json, renovate.jsonc, and renovate.json5 first, then .github/renovate.json and its .jsonc and .json5 variants, then .gitlab/renovate.json variants, then .renovaterc files, and finally a renovate section in package.json. The configuration options page marks the package.json location as deprecated, so a dedicated JSON file is the safer choice. A config change on a feature branch has no effect until it merges to the default branch.

A Baseline renovate.json

A baseline config needs a schedule, grouped non-major updates, and a narrow automerge rule. Renovate applies packageRules in order, and later rules override earlier ones, so the broad rule goes first and the specific rule goes last.

The baseline below groups minor and patch updates into one pull request, automerges them, and gives lint tooling its own label. Lockfile maintenance is turned on so the lock file refreshes on its own schedule.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "schedule": ["before 6am on monday"],
  "labels": ["dependencies"],
  "lockFileMaintenance": { "enabled": true, "automerge": true },
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "matchCurrentVersion": "!/^0/",
      "groupName": "non-major dependencies",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchPackageNames": ["prettier", "eslint"],
      "addLabels": ["lint-{{depName}}"],
      "automerge": true
    }
  ]
}

The $schema key enables autocomplete and validation. labels replaces the label list, while addLabels inside a matched rule appends to it, and templates such as {{depName}} are supported per the configuration options. The matchCurrentVersion value "!/^0/" excludes pre-1.0 packages, which SemVer allows to change at any time. The schedule string uses Renovate’s Later-style syntax; the configuration options page recommends cron syntax for new setups.

Grouping Updates with packageRules

Grouping works through groupName on a packageRules entry. Any entries that share a groupName land in the same branch and pull request. The rule above produces one pull request for all non-major minor and patch updates, which keeps review load predictable.

Selectors such as matchDepTypes, matchPackageNames, and matchUpdateTypes decide which packages a rule covers. Teams that do not want to hand-write every group can start from shared collections in the group presets and general sharing patterns in the config presets.

Automerge: What Merges and What Blocks It

Renovate automerges only after required status checks pass, and it merges one pull request per target branch per run. Platform-native automerge is on by default; setting platformAutomerge to false turns it off, per the configuration options.

With platform automerge enabled, select at least one required status check in branch protection. Without one, GitHub can merge a pull request whose tests have not run. The automerge documentation also lists blockers: committer restrictions, required pull request reviews, CODEOWNERS files, and branch protection that requires pull requests for branch automerge. Its advice is to wait about two hours before troubleshooting a stalled automerge.

Vulnerability Alerts Get a Separate Budget

Vulnerability fixes do not share the routine concurrency budget. prConcurrentLimit inside a vulnerabilityAlerts object sets a separate cap, and its default of 0 means no limit, so alerts keep their own queue. The configuration options page states that vulnerability alerts ignore schedule, commitHourlyLimit, and prHourlyLimit.

The same page sets vulnerabilityFixStrategy to lowest by default, which proposes the earliest fixed version. Setting it to highest makes Renovate use its normal upgrade choice instead.

CI Integration with the GitHub Action

The official renovatebot/github-action runs Renovate self-hosted inside a workflow. Its README documents the token, renovate-version, and renovate-image inputs, and it accepts LOG_LEVEL: debug for troubleshooting. The workflow below runs weekly and on demand instead of on every push.

on:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:
jobs:
  renovate:
    runs-on: ubuntu-latest
    steps:
      - uses: renovatebot/github-action@v46.3.8
        with:
          token: ${{ secrets.RENOVATE_TOKEN }}
          renovate-version: 44.181.1
        env:
          LOG_LEVEL: debug

The README pins the Action tag and the Renovate release separately, so update both when you upgrade. The token needs the workflow scope if Renovate should update workflow files. Without it, GitHub blocks pull requests that change a workflow, such as an actions/checkout bump.

Running Renovate Outside GitHub Actions

The running Renovate guide lists several options. The npm package renovate runs once across the configured repositories and exits, which suits cron jobs and ephemeral runners. Docker images are published as renovate/renovate and ghcr.io/renovatebot/renovate. The default image installs required tools at runtime, while the -full image bundles them in advance and weighs several gigabytes.

The guide also covers a GitLab Runner project and the Mend Renovate Community and Enterprise editions for stateful hosting. On any platform other than github.com, set a read-only github.com token in RENOVATE_GITHUB_COM_TOKEN so changelogs can be fetched. The docs also recommend a dedicated Renovate username, because sharing an identity with other bots can cause flip-flopping.

Comparison Table: Renovate Options at a Glance

The table below lists the configuration surfaces this guide uses and where each one is documented. Each row links to the page that defines it.

Concern	Renovate setting	Where it is documented
Config location	Repo file on the default branch, multiple formats	configuration options
Grouped pull requests	`groupName` on a `packageRules` entry	configuration options
Lockfile refresh	`lockFileMaintenance` with `automerge`	automerge documentation
Native automerge	`platformAutomerge` (default on)	configuration options
Security fixes	`vulnerabilityAlerts.prConcurrentLimit`	configuration options
Run in CI	`renovatebot/github-action`	GitHub Action README

For GitHub-native alternatives, see the Dependabot documentation.

Failure Modes and How the Docs Handle Them

Four failure modes come up repeatedly in the official material. Each has a configuration or token fix, and none requires redesigning the pipeline.

Automerge stalls on a busy default branch. Renovate needs a clean gap to merge into, and constant pushes to the default branch can prevent one. The automerge documentation recommends waiting about two hours before troubleshooting.

Workflow-file updates fail without the workflow scope. The token needs that scope before Renovate can open pull requests that change workflow files. The GitHub Action README documents this requirement.

Changelog and rate-limit problems on non-github.com platforms. Without a read-only github.com token, changelog lookups and API limits can break. Set RENOVATE_GITHUB_COM_TOKEN, per the running Renovate guide.

Vulnerability pull requests flood the queue. Alerts ignore the routine schedule by design. Setting prConcurrentLimit inside vulnerabilityAlerts caps them, as the configuration options page describes.

FAQ

Why isn’t Renovate automerging my pull requests?

Renovate waits for required checks and merges one pull request per target branch per run. Reviews, CODEOWNERS, committer restrictions, and branch protection can all block the merge. The automerge documentation advises waiting about two hours before troubleshooting.

Why can’t Renovate update my workflow files?

The token needs the workflow scope. Without it, GitHub rejects pull requests that change workflow files, such as an actions/checkout bump. The GitHub Action README documents this requirement.

Should I use the default or -full Docker image?

The default image installs tools at runtime and stays small. The -full image bundles tools in advance and is several gigabytes. The running Renovate guide describes that tradeoff.

How do I stop vulnerability pull requests from flooding the queue?

Set prConcurrentLimit inside the vulnerabilityAlerts object. Its default of 0 means no limit. The configuration options page documents the separate budget.

Where does Renovate look for its config file?

Renovate reads config only from the default branch, checking the listed file names in order and stopping at the first match. The configuration options page gives the full order.

The Bottom Line

Renovate suits teams that want grouped, scheduled, selectively automerged dependency updates and accept a larger configuration surface to get them. Its official docs cover config discovery, automerge blockers, vulnerability budgets, and several hosting options in enough detail to build from. The main risks are predictable: missing required checks, a missing workflow token scope, and an unbounded vulnerability queue. Set those three correctly before enabling automerge.

This guide is assembled from official documentation and community reports — we did not run this build ourselves.

NoCode Insider — AI workflow automation with no-code tools, agents, and APIs
Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows

Cross-links automatically generated from CodeIntel Log.