Renovate component

Renovate is a tool to automate dependency updates. This component allows you to run Renovate in a GitLab CI pipeline and update dependencies in your projects.

Also see lint-renovate

Use the shared Renovate administrator model by default. See group service account setup and the isolated group runner option.

Concept

Security Model

Variables

Name	required	Hints
GITLAB_TOKEN	yes	Permissions `api`, `read_api`, `read_registry`
GITHUB_TOKEN	optional	deprecated, see below
RENOVATE_GIT_PRIVATE_KEY	optional	SSH or PGP private key used by Renovate to sign Git commits. The component can bootstrap an SSH signing key when this is missing.
RENOVATE_NODE_ARGS	optional	Custom configuration for the NodeJS process Renovate runs in, see Configure memory usage below
CI_RENOVATE_CONFIG	optional	Shared Renovate configuration used when the repository has no config file and the component `config` input is empty.

Setup

Create or reuse the service account called renovate
Create a repository called renovate-runner
Populate variable GITLAB_TOKEN with a token of renovate
Create the pipeline configuration for the repository renovate-runner
Create the pipeline schedule e.g. once a day starting after 0:00 for the repository renovate-runner. The schedule must match the renovate presets-schedule.

Verified commits

The component enables Renovate commit signing by default. When RENOVATE_GIT_PRIVATE_KEY contains an SSH private key, the job derives its public key and checks the authenticated GitLab user's SSH keys. The job adds the public key with signing scope when it is missing. It stops before Renovate runs when the private key is invalid, the matching key has authentication-only scope, or the GitLab API cannot verify or register the key. PGP private keys are passed directly to Renovate.

When RENOVATE_GIT_PRIVATE_KEY is missing and verified-commits is enabled, the job generates an Ed25519 SSH signing key, adds the public key to the authenticated GitLab user with signing scope, stores the private key in the runner project variable RENOVATE_GIT_PRIVATE_KEY, and exports it for the current run.

The bootstrap requires the GITLAB_TOKEN/RENOVATE_TOKEN user to have permission to add SSH keys to its own account and create or update CI/CD variables in the runner project. The job stops if it cannot register the public key. A failure to persist a newly generated private key logs a warning, but the current job still uses that key. To manage the signing key yourself, create RENOVATE_GIT_PRIVATE_KEY before the first run. To disable automatic setup and key validation:

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      verified-commits: false

spec:
  inputs:
    extra-flags:
      description: 'Extra flags to pass to renovate. --autodiscover-filter="xrow-public/example-project" or --autodiscover-namespaces="xrow-public,xrow-shared"'
      default: ""
      type: string
    log-level: 
      default: info
      type: string
      options: [debug, info, warn, error, fatal]

---

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      onboarding-config: '{"$$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["local>mygroup/renovate-config"] }'
      extra-flags: '$[[ inputs.extra-flags ]]'
      log-level: '$[[ inputs.log-level ]]'
      repository-cache: enabled

...
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      ...
      extra-flags: "--autodiscover-namespaces=mygroup/*"

Create a repository called renovate-config with presets according to the documentation.

Shared runner configuration

Set CI_RENOVATE_CONFIG as a CI/CD variable on the runner project, its parent group, or the GitLab instance to provide the same self-hosted Renovate configuration to multiple runner pipelines. The value must be valid content for the file selected by the config-file input, which defaults to config.js. For example:

module.exports = {
  extends: ["local>mygroup/renovate-config"],
};

The component selects the configuration in this order:

The config file already present in the repository.
The component's config input.
The CI_RENOVATE_CONFIG CI/CD variable.
The component's default configuration.

Use the component's config input for a runner-specific override. Keep credentials in separate masked CI/CD variables and reference them through process.env instead of placing secrets directly in CI_RENOVATE_CONFIG, because the generated configuration is printed in the job log.

`renovate-config` example

You can see renovate-config as an example.

The basic renovate workflow of renovate-config

Do not interfere when developers work.
Renovate will run once a day.
Renovate will try to merge minor and patch updates on weekends.
Accept major updates via the dependency dashboard in your project.

Project onboarding

Add the renovate bot as a maintainer to the root groups. If you want to exclude renovate from automerge, degrade it to the role developer.
In GitLab enable Merge checks, ensure "Pipelines must succeed" is checked.
Configure a renovate.json in your project root or accept the onboarding ticket. Each new project will have an onboarding merge request Configure Renovate.

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

The setup is now complete and you will receive a Dependency Dashboard and updates from the renovate bot.
Set your .gitattributes to define collapse behavior.

# Do not collapse package-lock.json
package-lock.json text=auto eol=lf -gitlab-generated

Upgrading arbitrary software dependencies

The renovate-config includes some rules for upgrading arbitrary software dependencies. Here are examples on how to use them.

Containerfile example:

# renovate: datasource=gitlab-releases depName=gitlab-org/cli
ARG GLAB_VERSION=1.82.0
RUN dnf install -y https://gitlab.com/gitlab-org/cli/-/releases/v${GLAB_VERSION}/downloads/glab_${GLAB_VERSION}_linux_amd64.rpm

GitLab CI example:

# renovate: datasource=gitlab-releases depName=gitlab-org/cli
variables:
  GLAB_VERSION: 1.82.0

Project offboarding

Remove the renovate bot from your group or project.

Configure access to GitHub dependencies

Add variable GITHUB_TOKEN

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      host-rules:
      ...
      - matchHost: github.com
        token: "${GITHUB_TOKEN}"

Configure access to your private registry

Add variable MY_REGISTRY_USERNAME
Add variable MY_REGISTRY_PASSWORD

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      host-rules:
      ...
      - matchHost: registry.example.com
        username: "${MY_REGISTRY_USERNAME}"
        password: "${MY_REGISTRY_PASSWORD}"
      - matchHost: registry.redhat.io
        username: "${RH_REGISTRY_USERNAME}"
        password: "${RH_REGISTRY_PASSWORD}"

Example: Configure permission a Harbor read all user.

Add the following permissions for all projects:

Artifact: List, Read
Repository: List, Pull, Read
Tag: List

Container registries with many tags

The component fetches up to 100 pages of container tags by default. This exceeds the Renovate default because registries such as the Red Hat Ecosystem Catalog can expose thousands of tags while limiting each response page. Set docker-max-pages if a registry needs a different limit:

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/renovate-runner@stable
    inputs:
      docker-max-pages: 150

GitLab package registry access

The default Renovate configuration authenticates against the current GitLab instance for the package registry types commonly hosted by GitLab. The component configures host rules for the GitLab platform, container registry, and package registry access for Maven, npm, NuGet, PyPI, Helm, Terraform modules, Ruby gems, and Go packages automatically. Use host-rules only when a project needs different credentials or an additional external registry.

The component resolves the login of the user represented by GITLAB_TOKEN, RENOVATE_TOKEN, or CI_JOB_TOKEN through the GitLab API, exports it as CI_RENOVATE_USER_LOGIN, and uses that login for the built-in NuGet and container registry host rules.

Configure memory usage

Sometimes Renovate fails with 'Out of Memory' errors. For example, see Renovate OOM issues on Kubernetes. When this happens, provide more memory with the following at the beginning of your pipeline configuration:

variables:
  RENOVATE_NODE_ARGS: "--max-old-space-size=4096"
  KUBERNETES_MEMORY_REQUEST: "4Gi"
  KUBERNETES_MEMORY_LIMIT: "8Gi"

Optimize the values according to your needs. The CI/CD variables KUBERNETES_MEMORY_REQUEST and KUBERNETES_MEMORY_LIMIT are a standard way to overwrite container resources in the GitLab runner.

Configuring renovate for projects by example

Usage in projects with Helm charts

We assume that your project does not contain Helm subchart archives. If it does, you must enable the helmUpdateSubChartArchives feature to ensure these are kept up to date.

To let Renovate update a chart's appVersion, add a dependency annotation immediately before the key:

# renovate: datasource=docker depName=docker.io/library/alpine
appVersion: "3.20.0"

Add versioning=<strategy> to the annotation when the dependency does not use the default semver-coerced versioning strategy.

Local debugging of renovate

npm i -g renovate
export LOG_LEVEL=debug
export RENOVATE_GITHUB_COM_TOKEN='XXX'
npx renovate --platform=local --repository-cache=reset

Debug renovate

Look in the pipeline runs of the runner project.
Look at the dashboard of your renovated project, see the open PRs and the dependency status.
Turn on the debug flag

Inputs

Name	Description	Default	Type
---	---	---	---
autodiscover	Whether to enable autodiscovery for Renovate	true	string
ca-certs-path	The path to the CA certificates file		string
config	Configuration to configure Renovate		string
config-file	Path to the configuration file for Renovate	config.js	string
docker-max-pages	Maximum number of tag pages Renovate fetches from a container registry	100	number
extra-flags	Extra flags to pass to Renovate such as --autodiscover-filter=group/* or --autodiscover-namespaces=group1,group2		string
host-rules	Global host rules to configure Renovate for private registries	[]	array
ignore-pr-author	Whether to ignore the author of the pull request	false	boolean
log-file-level	The log level to use for Renovate in the log file	debug	string
log-level	The log level to use for Renovate	info	string
name	The name of the job to create	renovate	string
needs	The jobs that this job depends on.	[]	array
onboarding-config	Contents of the Renovate onboarding configuration file	{"$$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["config:recommended"] }	string
repository-cache	Decide if Renovate uses a JSON cache to speed up extractions. See https://docs.renovatebot.com/self-hosted-configuration/#repositorycache	disabled	string
rules	The jobs that this job depends on.	[{"if":"($CI_PIPELINE_SOURCE == \"web\" \|\| $CI_PIPELINE_SOURCE == \"schedule\")","when":"on_success"},{"when":"never"}]	array
stage	The stage to run the job in	build	string
timeout	Timeout for the Renovate job	2h	string
verified-commits	Validate a configured signing key or bootstrap Renovate SSH commit signing when RENOVATE_GIT_PRIVATE_KEY is not set	true	boolean

Concept​

Security Model​

Variables​

Setup​

Verified commits​

Shared runner configuration​

renovate-config example​

Project onboarding​

Upgrading arbitrary software dependencies​

Project offboarding​

Configure access to GitHub dependencies​

Configure access to your private registry​

Container registries with many tags​

GitLab package registry access​

Configure memory usage​

Configuring renovate for projects by example​

Usage in projects with Helm charts​

Local debugging of renovate​

Debug renovate​

Inputs​