Renovate can automate your dependency updates, similar to what you might have seen with Dependabot. But where Dependabot requires a community maintained project to run on GitLab.com, Renovate integrates nicely with GitLab.com through official support.

In this blogpost we will walk through setting up Renovate for use on GitLab.com.

We will set up:

  1. discovery and onboarding of projects,

  2. merge request management through GitLab Issues,

  3. integrate with GitLab Container & Package Registry,

  4. automatically merge small dependency updates.

Getting started on GitLab.com

Renovate themselves provide some documentation on getting started. We will follow along while showing you the absolute minimum of configuration you need, and highlight the steps needed to achieve our outlined goals.

Either fork https://gitlab.com/renovate-bot/renovate-runner directly, or create a new project to hold a minimal subset of configuration. The benefit of forking the original repository is that you immediately document it’s origin, and get the README.md that goes with it. The downside of forking the original is that you get more than what you need, which can be confusing at times.

At minimum you will want a repository that least contains the following.

CI/CD pipeline

Renovate will run as a scheduled CI/CD pipeline, and as such will need a .gitlab-ci.yml file just like any other pipeline. The provided pipeline runner templates use imports to reduce duplication, but you can just as well combine these into one if you prefer.

Listing 1. .gitlab-ci.yml
include: '/templates/renovate.gitlab-ci.yml'

This .gitlab-ci.yml file refers to:

/templates/renovate.gitlab-ci.yml 
include: '/templates/_common.gitlab-ci.yml'

image: ${CI_RENOVATE_IMAGE}

variables:
  CI_RENOVATE_IMAGE: renovate/renovate:32.122.0@sha256:b416e3ac7dfb449fbc482cc89e77fbeea0cf0248d449d05a08e56f56083cc134

Which in turn refers to:

/templates/_common.gitlab-ci.yml 
variables:
  RENOVATE_BASE_DIR: $CI_PROJECT_DIR/renovate
  RENOVATE_ENDPOINT: $CI_API_V4_URL
  RENOVATE_PLATFORM: gitlab
  RENOVATE_ONBOARDING_CONFIG: '{"$$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["config:base"] }'
  RENOVATE_OPTIMIZE_FOR_DISABLED: 'true'
  RENOVATE_REPOSITORY_CACHE: 'enabled'
  RENOVATE_REQUIRE_CONFIG: 'required'
  RENOVATE_ONBOARDING: 'false'
  RENOVATE_IGNORE_PR_AUTHOR: 'true'
  RENOVATE_EXTENDS: 'github>whitesource/merge-confidence:beta'
  RENOVATE_LOG_FILE: renovate-log.ndjson
  RENOVATE_LOG_FILE_LEVEL: debug
  LOG_LEVEL: info

default:
  cache:
    key: ${CI_COMMIT_REF_SLUG}-renovate
    paths:
      - renovate/cache/renovate/repository/

renovate:
  stage: deploy
  resource_group: production
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
  script:
    - renovate $RENOVATE_EXTRA_FLAGS
  artifacts:
    when: always
    expire_in: 1d
    paths:
      - '$RENOVATE_LOG_FILE'

Renovate Config

Self-hosted Renovate configuration is stored inside config.json, with a minimal sample provided below. This is where you would override any of the default values, as well as define specific package rules.

Listing 2. config.js
module.exports = {
  labels: ["dependencies"],
  hostRules: [
    {
      hostType: 'maven',
      matchHost: 'gitlab.com',
      token: process.env.RENOVATE_TOKEN, (1)
    }
  ],
  includeForks: true, (2)
  platformAutomerge: true, (3)
  packageRules: [
    {
      "description": "Auto merge small changes as per https://docs.renovatebot.com/configuration-options/#automerge",
      "matchUpdateTypes": ["patch", "pin", "digest"], (4)
      "automerge": true
    }
  ]
};
1 hostRules allows us to pass credentials for GitLab Package & Container Registry. That way dependencies on internal libraries are also upgraded.
2 We set includeForks to true to bump our fork of renovate-runner, as well as other separately maintained forks.
3 platformAutomerge integrates with GitLab to merge once the project CI/CD pipelines complete successfully.
4 We automatically merge small version changes through matchUpdateTypes.

CI/CD Variables

We will need to configure the token CI/CD Variables as indicated in the README, with appropriate scope and access.

Specifically for RENOVATE_EXTRA_FLAGS we will use --autodiscover=true --autodiscover-filter=ACME/** --onboarding=true. That way projects are automatically discovered and onboarded through a merge request.

Scheduled pipeline

Finally, to run the CI/CD pipeline, we create a schedule to run early in the day. Workday mornings work best for us, to start the day with fresh new dependencies, or pipelines to fix.

Pipeline Schedules
Figure 1. Pipeline Schedules

What to expect

When all the above is configured correctly, you can start a first run from the scheduled pipeline manually.

Onboarding

When first run, Renovate will create onboarding merge requests for discovered projects. As indicated, this merge request can be merged or closed, depending on if you want to start using Renovate for that project.

Onboarding merge requests
Figure 2. Onboarding merge requests

Dependency dashboard

Once a project is configured to use Renovate, an issue will be opened where you can manage merge requests created for the project. Any merge requests pending, or previously closed are listed here. Note that you need another Renovate run after making any changes on any dashboard.

Dependency Dashboard per project
Figure 3. Dependency Dashboard per project

Update dependencies

Individual dependencies are typically updated through individual merge requests, such as this one for the Slack Java API. Release notes are included here, with a link back to the source, to allow you to evaluate suitability and further changes.

Update dependency merge requests
Figure 4. Update dependency merge requests

Footnotes

Running Renovate on GitLab allows you to easily keep up to date with new dependency versions. At the very least you will be aware of new versions coming out, even when more changes are needed. When more changes are needed, look for tools like OpenRewrite to see if migration recipes are available.

Tested with Renovate 32.122.0.

shadow-left