Renovate

Renovate opens pull requests that update dependencies (Docker images, GitHub Actions, npm, Go, Compose files, Helm charts, Terraform providers and more) and can automerge the safe ones. It is configured with a JSON config file in each repo, usually extending a shared preset. Updated Actions versions are covered in GitHub Actions, Woodpecker steps in Woodpecker CI, image tags in CI Docker Builds and Docker-Compose.

Documentation: Renovate docs, Configuration options, Preset reference, Config validation

Minimal renovate.json #

Renovate looks for renovate.json, renovate.json5, .github/renovate.json, .gitlab/renovate.json, .renovaterc and a renovate key in package.json.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"]
}

config:recommended enables the Dependency Dashboard, groups common monorepo and workspace packages, and enables sensible defaults.

Shared Preset Pattern #

Keep one preset repo and extend it everywhere. This repo’s renovate.json is only:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["github>modem7/renovate-config"]
}

The preset repo (modem7/renovate-config) holds default.json (extends shared), shared.json, automergePatch.json, automergeDigest.json and docker.json. A repo can opt in to extras:

{
  "extends": [
    "github>modem7/renovate-config",
    "github>modem7/renovate-config:automergePatch",
    "github>modem7/renovate-config:docker"
  ]
}

Common Top-Level Options #

packageRules #

Rules are evaluated top to bottom; later matching rules override earlier ones. All match* conditions in a rule must hold.

{
  "packageRules": [
    {
      "description": "Automerge minor and patch for dev dependencies",
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "description": "Group all GitHub Actions updates",
      "matchManagers": ["github-actions"],
      "groupName": "github actions"
    },
    {
      "description": "Majors need a human and a wait",
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "minimumReleaseAge": "7 days",
      "addLabels": ["major"]
    },
    {
      "description": "Hold back one image",
      "matchPackageNames": ["postgres"],
      "allowedVersions": "<18"
    },
    {
      "description": "Never touch these",
      "matchPackageNames": ["/^internal\\//"],
      "enabled": false
    }
  ]
}

Actions on a match: automerge, enabled, groupName, schedule, labels, addLabels, assignees, allowedVersions, versioning, pinDigests, minimumReleaseAge, extends (apply a preset)

Automerge #

{
  "extends": [":automergeDigest", ":automergePatch"],
  "platformAutomerge": false,
  "packageRules": [
    {
      "matchManagers": ["github-actions", "woodpecker"],
      "matchUpdateTypes": ["minor", "patch", "digest"],
      "automerge": true
    }
  ]
}

• Automerge needs required status checks to pass, so give the repo CI (see CI Recipes) or set ignoreTests.
• platformAutomerge: true uses GitHub’s own auto-merge and requires branch protection with required checks; false makes Renovate merge on its next run.
• Run Renovate often enough (hourly) for automerge to complete; each run only merges a PR that is up to date and green.
• Keep majors manual. Digest and patch updates of CI plumbing are good automerge candidates.

Schedules #

{
  "timezone": "Europe/London",
  "schedule": ["before 6am on monday"],
  "packageRules": [
    {
      "matchUpdateTypes": ["digest"],
      "extends": ["schedule:nonOfficeHours"]
    }
  ],
  "lockFileMaintenance": { "enabled": true, "schedule": ["before 4am on the first day of the month"] }
}

Schedules use “later” syntax (after 10pm every weekday, every weekend). Renovate still has to run during that window. Items outside the schedule appear in the Dependency Dashboard and can be forced with its checkbox.

Custom (Regex) Managers #

Use these for versions in arbitrary files. A comment above the value tells Renovate where to look it up.

# compose.yaml / workflow / Dockerfile
env:
  NODE_VERSION: 22.12.0 # renovate: datasource=node-version depName=node
  # or
ARG S6_OVERLAY_VERSION=3.2.0.2

{
  "customManagers": [
    {
      "customType": "regex",
      "description": "Versions annotated with a renovate comment",
      "managerFilePatterns": ["/(^|/)Dockerfile$/", "/^\\.github/workflows/.+\\.ya?ml$/"],
      "matchStrings": [
        "[A-Z_]+_VERSION[=:] ?(?<currentValue>\\S+) # renovate: datasource=(?<datasource>\\S+) depName=(?<depName>\\S+)"
      ]
    },
    {
      "customType": "regex",
      "description": "Fixed upstream project via templates",
      "managerFilePatterns": ["/^Dockerfile$/"],
      "matchStrings": ["ARG S6_OVERLAY_VERSION=(?<currentValue>[0-9.]+)"],
      "datasourceTemplate": "github-releases",
      "packageNameTemplate": "just-containers/s6-overlay",
      "extractVersionTemplate": "^v(?<version>.*)$"
    }
  ]
}

Common datasources: github-releases, github-tags, docker, npm, pypi, go, helm, node-version.

The modem7/renovate-config:shared preset already ships two regex managers for version: and *_VERSION: values annotated with # renovate: datasource=... depName=... in .github/workflows/ and .woodpecker/ files.

Dependency Dashboard #

A GitHub/GitLab issue titled “Dependency Dashboard” lists every pending, open, rate-limited and errored update.

• Tick a box to force a PR now (bypasses schedule and rate limits) or to retry a failed one.
• Tick “Check this box to trigger a request for Renovate to run again” to rerun without waiting for the schedule.
• Detected dependencies are listed for debugging “why isn’t it updating X?”.
• Require approval for risky updates with "dependencyDashboardApproval": true in a packageRules entry (e.g. majors).

Validating Config #

npx --yes --package renovate -- renovate-config-validator            # checks the default config files
npx --yes --package renovate -- renovate-config-validator --strict   # also fails if the config needs migration

Run it with no filename for a normal repo: passing a filename makes the validator treat that file as global self-hosted config (use that form only for a self-hosted config.js). Run it in CI on PRs that touch the config, and as a pre-commit hook.

Self-Hosted vs the Mend Renovate App #

Self-hosted run with Docker:

docker run --rm \
  -e RENOVATE_TOKEN="$RENOVATE_TOKEN" \
  -e RENOVATE_PLATFORM=gitea \
  -e RENOVATE_ENDPOINT=https://git.example.com/api/v1 \
  -e RENOVATE_AUTODISCOVER=true \
  -e LOG_LEVEL=debug \
  renovate/renovate:<VERSION>

Run it on a schedule from GitHub Actions with the official action (see GitHub Actions) or from a Woodpecker cron job (Woodpecker CI) using the same container.

Troubleshooting #