GitLab CI template for Renovate¶

Automate your dependency updates with Renovate.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your .gitlab-ci.yml:

include:
  # include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/renovate/gitlab-ci-renovate@1.11.0

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

include:
  # include the template
  - project: "to-be-continuous/renovate"
    ref: "1.11.0"
    file: "/templates/gitlab-ci-renovate.yml"

Configuration¶

The Renovate template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
`image` / `RENOVATE_IMAGE`	The Docker image used to run Renovate	`docker.io/renovate/renovate:latest`
`autodiscover` / `RENOVATE_AUTODISCOVER`	Renovate configuration to enable repositories autodiscovery	`true`
`autodiscover-filter` / `RENOVATE_AUTODISCOVER_FILTER`	Renovate configuration to filter the list of autodiscovered repositories	`${CI_PROJECT_ROOT_NAMESPACE}/**`
`onboarding-config` / `RENOVATE_ONBOARDING_CONFIG`	Renovate configuration to use for onboarding Renovate	see below
`RENOVATE_TOKEN`	A GitLab access token to allow Renovate crawl your projects. See doc	none
`GITHUB_COM_TOKEN`	A GitHub access token to allow Renovate fetch changelogs. See doc	none

This template will help you using Renovate from a GitLab project to automate your dependency updates within your groups or projects. On the contrary to other to-be-continuous templates, this one should be used in a separate project that will be in charge of crawling all your other projects.

Upon including the template, carefuly follow Renovate's documentation to configure the bot accordingly. Pay attention to the following:

~~Remember to set the platform parameter to gitlab in your configuration.~~
GitLab platform integration requires that you declare a RENOVATE_TOKEN variable with an access token.
You'll also probaly need to declare a GITHUB_COM_TOKEN variable, holding a GitHub access token (for fetching changelogs)

Default Renovate configuration¶

This template is designed to be run on GitLab.

Defaults values are set to manage GitLab features :

Renovate variable	Value
`RENOVATE_PLATFORM`	`gitlab`
`RENOVATE_ENDPOINT`	`$CI_API_V4_URL`
`RENOVATE_REGISTRY_ALIASES`	`{"$$CI_SERVER_FQDN": "$CI_SERVER_FQDN", "$$CI_SERVER_URL": "$CI_SERVER_URL", "$$CI_SERVER_HOST": "$CI_SERVER_HOST", "$$CI_SERVER_PORT": "$CI_SERVER_PORT", "$$CI_REGISTRY": "$CI_REGISTRY", "$$CI_REPOSITORY_URL": "$CI_REPOSITORY_URL", "$$CI_DEPENDENCY_PROXY_SERVER": "$CI_DEPENDENCY_PROXY_SERVER"}`
`RENOVATE_BINARY_SOURCE`	`install`
`RENOVATE_LOG_FILE`	`renovate-log.ndjson`
`RENOVATE_LOG_FILE_LEVEL`	`debug`

Default onboarding configuration¶

The default onboarding configuration is suitable for projects using to-be-continuous:

looks for user-defined inputs and variables in your .gitlab-ci.yml defining Docker images (ex: SOMETOOL_IMAGE: docker.io/sometool:1.2.2)

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:best-practices"
  ],
  "labels": [
    "dependencies"
  ],
  "customManagers": [
    {
      "customType": "regex",
      "managerFilePatterns": [ "\\.gitlab-ci\\.ya?ml$" ], 
      "matchStrings": [ "\\s?_IMAGE:\\s['\"](?<registryUrls>.*?)\\/(?<depName>.*?):(?<currentValue>.*)['\"]" ], 
      "datasourceTemplate": "docker" 
    },
    {
      "customType": "regex",
      "managerFilePatterns": [ "\\.gitlab-ci\\.ya?ml$" ], 
      "matchStrings": [ "\\s?image:\\s['\"](?<registryUrls>.*?)\\/(?<depName>.*?):(?<currentValue>.*)['\"]" ], 
      "datasourceTemplate": "docker" 
    }
  ] 
}

Dry-run implementation details¶

Depending on the source of a pipeline, the template will either perform your dependency updates (create/update/delete branches and MRs) or perform a dry run (to preview the behavior of Renovate with logs, without making any changes to your repositories).

The real dependency updates is triggered only when:

the pipeline is started from the web interface (menu Build > Pipelines, click Run pipeline),
or the pipeline is started from a scheduled run (menu Build > Pipeline schedules).

In any other case (regular Git commit or else) the template will perform a dry run.

Dry-run behavior is enabled/disabled with the RENOVATE_DRY_RUN environment variable. Please don't try to override it or you might break the default template implementation.

Dependending on the number of projects to inspect, Renovate can use quite a lot of resources (especially cache). Moreover, if lots of dependencies need to be updated, lots of pipelines will be triggered which will again use lots of resources. Therefore make sure to choose a wise schedule for the Renovate job. Once a week seems to be a good starting point.

Variants¶

The Renovate template can be used in conjunction with template variants to cover specific cases.

Vault variant¶

This variant allows delegating your secrets management to a Vault server.

Configuration¶

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable	Description	Default value
`TBC_VAULT_IMAGE`	The Vault Secrets Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest`
`vault-base-url` / `VAULT_BASE_URL`	The Vault server base API url	must be defined
`vault-oidc-aud` / `VAULT_OIDC_AUD`	The `aud` claim for the JWT	`$CI_SERVER_URL`
`VAULT_ROLE_ID`	The AppRole RoleID	none
`VAULT_SECRET_ID`	The AppRole SecretID	none

By default, the variant will authenticate using a JWT ID token. To use AppRole instead the VAULT_ROLE_ID and VAULT_SECRET_ID should be defined as secret project variables.

Usage¶

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Parameter	Description
`secret_path` (path parameter)	this is your secret location in the Vault server
`field` (query parameter)	parameter to access a single basic field from the secret JSON payload

Example¶

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/renovate/gitlab-ci-renovate@1.11.0
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/renovate/gitlab-ci-renovate-vault@1.11.0
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"

variables:
  # Secrets managed by Vault
  RENOVATE_TOKEN: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/renovate/gitlab?field=token"
  GITHUB_COM_TOKEN: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/renovate/github?field=token"