Dependency updates

Vortex provides Renovate configuration for your project's automated dependency updates.

How updates are organized

All Renovate PRs use the branch prefix deps/ and are labeled Dependencies. Assignees can be configured in the assignees field.

Update rules

Group	Packages	Update types	Schedule	Minimum release age
Drupal core	drupal/core-recommended, drupal/core-composer-scaffold, and other drupal/core-* packages	Minor, patch	Daily before 2 AM UTC	None
Drupal contrib and PHP packages (non-core)	All Drupal contrib modules and non-Drupal Packagist packages	Minor, patch	Weekly, Sunday before 2 AM UTC	14 days for Packagist packages
JS packages	All npm packages (root package.json only)	Minor, patch	Weekly, Sunday before 2 AM UTC	14 days
Container images	All images in .docker/ and docker-compose.yml	Major, minor, patch	Daily before 3 AM UTC	14 days for Docker Hub images
CI tools	npm packages that CI runs at a pinned version through npx	Major, minor, patch	Daily before 3 AM UTC	14 days
Renovate image	The renovate/renovate image in .circleci/update-dependencies.yml	Major, minor, patch	Weekly, Sunday before 3 AM UTC	14 days
GitHub Actions	All actions (pinned to digests)	Major, minor, patch	Daily before 3 AM UTC	14 days

Renovate publishes several releases a day, so the image that runs Renovate in CircleCI has a group of its own with a weekly schedule. In the daily CI tools group, a new version would be proposed almost every day.

Auto-merge

Every group auto-merges by default: GitHub merges the PR as soon as it meets the base branch's protection rules, such as passing required status checks and any required reviews. Each group in renovate.json lists an explicit automerge flag, so you can see and change the behavior per group. To merge a group's PRs yourself, set its flag to false:

{
    "groupName": "PHP - Drupal core - Minor and patch",
    "groupSlug": "php-drupal-core-minor-patch",
    ...
    "automerge": false
}

The installer asks which groups to auto-merge and sets the flag to true for the groups you select and to false for the rest. The CI tools choice covers the Renovate image group too. When you update Vortex, it preselects the groups whose flag is already true, so your choices carry over.

Auto-merge requires 2 repository settings:

1. "Allow auto-merge" enabled under Settings > General > Pull Requests.
2. "Require status checks to pass before merging" configured in the base branch's branch protection rules, with at least 1 required status check selected. Otherwise, GitHub may merge even if CI is red.

Every required status check must also report on deps/* branches. A check that never reports, such as a CircleCI job that a branch filter excludes from deps/* branches, keeps the PR blocked indefinitely. A GitHub Actions job skipped by its if condition reports as skipped, which satisfies the requirement.

Minimum release age

Renovate holds back a new release until it's 14 days old in every group except Drupal core. A compromised release is often detected and pulled from its registry within days. Nobody reviews an auto-merged update, so the delay keeps such a release out of your project. Renovate recommends 14 days when you auto-merge third-party dependencies.

Each delayed group sets minimumReleaseAge next to its automerge flag:

{
    "groupName": "JavaScript - All packages - Minor and patch",
    "groupSlug": "js-all-minor-patch",
    ...
    "minimumReleaseAge": "14 days",
    "automerge": true
}

Renovate doesn't create the branch or the PR until a release has reached that age, which the top-level "internalChecksFilter": "strict" setting enforces. When the newest release is too young, Renovate proposes the newest one that isn't, and a grouped PR leaves out the packages that have nothing old enough yet. Because the PR only exists once the delay has passed, GitHub's auto-merge can't merge a release early.

The delay adds to each group's schedule: a weekly group proposes a release 14 to 21 days after it's published, and a daily group 14 to 15 days after.

Drupal core

Drupal core has no delay, so a core security release is proposed on the next daily run. Its rule in renovate.json carries a description that says so.

Registries without release dates

Renovate can only hold back a release when its registry records when the release was published. Of the registries Vortex uses, Drupal.org (Drupal contrib modules) and GitHub Container Registry (the Gitleaks image) don't, so their updates arrive without the delay. The top-level "minimumReleaseAgeBehaviour": "timestamp-optional" setting lets these updates through; without it, Renovate would hold them back indefinitely. The logLevelRemap entry stops Renovate from reporting them as a repository problem on the Dependency Dashboard.

Docker Hub records release dates, but Renovate can't read them for an image with more than 1,000 tags. The Renovate image has tens of thousands of tags, so Vortex looks its versions up in the renovate npm package instead. The package uses the same version numbers and records a date for every release.

GitHub Actions are aged by the date of the commit that a tag points to. The action's publisher controls that date, so for actions the delay is a weaker safeguard than for packages from a registry.

Security fixes

When Renovate can read your repository's Dependabot alerts, it raises a fix for a published advisory straight away, without the delay or the schedule. Otherwise, a security fix arrives as a routine update and waits like any other. To apply one sooner, update the dependency yourself, or request the pending update from the Dependency Dashboard.

Changing the delay

To change the delay for a group, edit its minimumReleaseAge. To remove the delay, delete the key. Turning auto-merge off for a group keeps its delay, so delete the key as well if you want those PRs as soon as a release is published.

Updates waiting for their release to reach the minimum age are listed under Pending Status Checks on the Dependency Dashboard, where you can also request one early. The self-hosted service turns the dashboard off by default: set RENOVATE_DEPENDENCY_DASHBOARD to true to see them.

Configuration

The configuration is stored in renovate.json. It's based on the Renovate configuration for automated Drupal dependency updates project.

PR throughput and presentation

• Concurrent PR limit: prConcurrentLimit: 10 - at most 10 open PRs across all groups at any time.
• Hourly PR limit: prHourlyLimit: 0 - no hourly cap; the per-group schedules listed earlier provide throttling.
• Commit body table: commitBodyTable: true - grouped update commits include a version-comparison table in the commit message body.
• Dashboard labels: the Renovate dependency dashboard issue is labeled Dependencies (dependencyDashboardLabels).

Disabled updates

Renovate intentionally skips these updates. Update them manually:

Group	What's skipped	Why
Drupal core major	drupal/core-recommended, drupal/core-composer-scaffold, and other drupal/core-* packages	Major version upgrades may introduce breaking changes
PHP and Drupal contrib major	All Drupal contrib modules and non-Drupal Packagist packages	Major version upgrades may introduce breaking changes
JS major	All npm packages	Major version upgrades may introduce breaking changes
PHP language version	php constraint in composer.json	Major version upgrades may introduce breaking changes
JS language versions	node, npm in package.json	Major version upgrades may introduce breaking changes
JS non-root packages	Any package.json not at the root	Theme dependencies are managed separately

Continuous integration

Renovate can run as a hosted GitHub app or as a standalone self-hosted service in CircleCI or GitHub Actions. A self-hosted service suits projects that restrict third-party access to their repositories.

note

If the job is configured but a required variable isn't provided, the job still runs and the Renovate update steps are skipped gracefully without failing the build. On GitHub Actions the required variables are RENOVATE_TOKEN and RENOVATE_GIT_AUTHOR; CircleCI additionally requires RENOVATE_REPOSITORIES, since it has no repository to default to.

Setting up the self-hosted service

GitHub Actions

Required variables, created in the GitHub repository settings:

• RENOVATE_TOKEN: GitHub access token with repository write permissions. Location: Settings > Secrets and variables > Actions > Repository secrets.
• RENOVATE_GIT_AUTHOR: Author for Renovate commits in the format Name <email@example.com> (for example, Renovate Bot <renovate@example.com>). Location: Settings > Secrets and variables > Actions > Repository variables.

Optional variables (defaults apply if not set):

• RENOVATE_REPOSITORIES: Repository to run Renovate on in the format yourorg/repo (default: the current repository).
• RENOVATE_DRY_RUN: Set to true to test runs without making changes (default: false).
• RENOVATE_DEPENDENCY_DASHBOARD: Set to true to enable the dependency dashboard (default: false).

Manual trigger: run the workflow from the Actions tab using the workflow dispatch feature. A manual run skips the schedules, but not the minimum release age.

Debug logging: set the LOG_LEVEL environment variable to debug in the workflow configuration.

CircleCI

Required variables, created in the CircleCI project settings:

• RENOVATE_TOKEN: GitHub access token with repository write permissions.
• RENOVATE_REPOSITORIES: Repository to run Renovate on in the format yourorg/repo.
• RENOVATE_GIT_AUTHOR: Author for Renovate commits in the format Name <email@example.com> (for example, Renovate Bot <renovate@example.com>).

Optional variables (defaults apply if not set):

• RENOVATE_DRY_RUN: Set to true to test runs without making changes (default: false).
• RENOVATE_DEPENDENCY_DASHBOARD: Set to true to enable the dependency dashboard (default: false).

Manual trigger: trigger the Renovate job from the CircleCI pipeline UI.

Scheduled trigger: add an update-dependencies scheduled trigger under Project Settings → Triggers with config source update-dependencies.yml and branch develop.

Renovate version: the job runs a pinned renovate/renovate image, which Renovate keeps up to date through the Renovate image group.

Debug logging: enabled by default with LOG_LEVEL: 'debug'.

Triggering GitHub Actions from the self-hosted service isn't supported.

Dependency dashboard

The Renovate Dependency Dashboard is a GitHub issue that lists:

• Available dependency updates that are scheduled for later execution
• Updates waiting for their release to reach the minimum release age
• Updates that have been filtered out due to configuration rules
• Failed update attempts and their reasons

The dashboard is created with the title "RenovateBot Dependency Dashboard (self-hosted)" when running in self-hosted mode.