mirror of
https://github.com/renovatebot/renovate.git
synced 2025-01-16 01:26:24 +00:00
274 lines
14 KiB
Markdown
274 lines
14 KiB
Markdown
---
|
|
title: Shareable Config Presets
|
|
description: Renovate's support for ESLint-like shareable configs
|
|
---
|
|
|
|
# Shareable Config Presets
|
|
|
|
This document describes how to configure your shared presets.
|
|
Read the [Key concepts, presets](./key-concepts/presets.md) page to learn more about presets in general.
|
|
|
|
Shareable config presets can only be used with the JSON format, other formats are not supported.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! warning
|
|
`default.json` is intended for use with presets only!
|
|
Also, do not use a `renovate.json` file as a preset.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! info
|
|
We've deprecated the use of a `renovate.json` file for presets as this can cause issues if the repository configuration uses a `renovate.json` file as well.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! tip
|
|
Describe what your preset is doing by using the `"description"` field.
|
|
This way your configuration is self-documenting.
|
|
|
|
## Extending from a preset
|
|
|
|
To use a preset put it in an `extends` array within your Renovate config.
|
|
Presets can be nested.
|
|
|
|
## Preset Hosting
|
|
|
|
Presets should be hosted in repositories, which usually means the same platform host as Renovate is running against.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! warning
|
|
npm-based presets are deprecated and support will be removed in a future major release.
|
|
|
|
You can set a Git tag (like a SemVer) to use a specific release of your shared config.
|
|
|
|
### GitHub
|
|
|
|
| name | example use | preset | resolves as | filename | Git tag |
|
|
| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- |
|
|
| GitHub default | `github>abc/foo` | `default` | `https://github.com/abc/foo` | `default.json` | Default branch |
|
|
| GitHub with preset name | `github>abc/foo:xyz` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | Default branch |
|
|
| GitHub with preset name (JSON5) | `github>abc/foo:xyz.json5` | `xyz` | `https://github.com/abc/foo` | `xyz.json5` | Default branch |
|
|
| GitHub default with a tag | `github>abc/foo#1.5.4` | `default` | `https://github.com/abc/foo` | `default.json` | `1.5.4` |
|
|
| GitHub with preset name with a tag | `github>abc/foo:xyz#1.5.4` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
| GitHub with preset name and path with a tag | `github>abc/foo//path/xyz#1.5.4` | `xyz` | `https://github.com/abc/foo` | `path/xyz.json` | `1.5.4` |
|
|
| GitHub with subpreset name and tag | `github>abc/foo:xyz/sub#1.5.4` | `sub` | `https://github.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
|
|
### GitLab
|
|
|
|
| name | example use | preset | resolves as | filename | Git tag |
|
|
| ------------------------------------------- | -------------------------------- | --------- | ---------------------------- | --------------- | -------------- |
|
|
| GitLab default | `gitlab>abc/foo` | `default` | `https://gitlab.com/abc/foo` | `default.json` | Default branch |
|
|
| GitLab with preset name | `gitlab>abc/foo:xyz` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | Default branch |
|
|
| GitLab with preset name (JSON5) | `gitlab>abc/foo:xyz.json5` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json5` | Default branch |
|
|
| GitLab default with a tag | `gitlab>abc/foo#1.5.4` | `default` | `https://gitlab.com/abc/foo` | `default.json` | `1.5.4` |
|
|
| GitLab with preset name with a tag | `gitlab>abc/foo:xyz#1.5.4` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
| GitLab with preset name and path with a tag | `gitlab>abc/foo//path/xyz#1.5.4` | `xyz` | `https://gitlab.com/abc/foo` | `path/xyz.json` | `1.5.4` |
|
|
| GitLab with subpreset name and tag | `gitlab>abc/foo:xyz/sub#1.5.4` | `sub` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
|
|
### Gitea
|
|
|
|
| name | example use | preset | resolves as | filename | Git tag |
|
|
| ------------------------------------------ | ------------------------------- | --------- | --------------------------- | --------------- | -------------- |
|
|
| Gitea default | `gitea>abc/foo` | `default` | `https://gitea.com/abc/foo` | `default.json` | Default branch |
|
|
| Gitea with preset name | `gitea>abc/foo:xyz` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | Default branch |
|
|
| Gitea with preset name (JSON5) | `gitea>abc/foo:xyz.json5` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json5` | Default branch |
|
|
| Gitea default with a tag | `gitea>abc/foo#1.5.4` | `default` | `https://gitea.com/abc/foo` | `default.json` | `1.5.4` |
|
|
| Gitea with preset name with a tag | `gitea>abc/foo:xyz#1.5.4` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
| Gitea with preset name and path with a tag | `gitea>abc/foo//path/xyz#1.5.4` | `xyz` | `https://gitea.com/abc/foo` | `path/xyz.json` | `1.5.4` |
|
|
| Gitea with subpreset name and tag | `gitea>abc/foo:xyz/sub#1.5.4` | `sub` | `https://gitea.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
|
|
### Self-hosted Git
|
|
|
|
| name | example use | preset | resolves as | filename | Git tag |
|
|
| ------------------------------------------ | ------------------------------- | --------- | ------------------------------------ | --------------- | -------------- |
|
|
| Local default | `local>abc/foo` | `default` | `https://github.company.com/abc/foo` | `default.json` | Default branch |
|
|
| Local with preset path | `local>abc/foo:xyz` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | Default branch |
|
|
| Local with preset path (JSON5) | `local>abc/foo:xyz.json5` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json5` | Default branch |
|
|
| Local default with a tag | `local>abc/foo#1.5.4` | `default` | `https://github.company.com/abc/foo` | `default.json` | `1.5.4` |
|
|
| Local with preset name with a tag | `local>abc/foo:xyz#1.5.4` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
| Local with preset name and path with a tag | `local>abc/foo//path/xyz#1.5.4` | `xyz` | `https://github.company.com/abc/foo` | `path/xyz.json` | `1.5.4` |
|
|
| Local with subpreset name and tag | `local>abc/foo:xyz/sub#1.5.4` | `sub` | `https://github.company.com/abc/foo` | `xyz.json` | `1.5.4` |
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! tip
|
|
You can't combine the path and sub-preset syntaxes.
|
|
This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported.
|
|
One workaround is to use distinct files instead of sub-presets.
|
|
|
|
## Example configs
|
|
|
|
An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing semver ranges".
|
|
It simply sets the configuration option `rangeStrategy` to `replace`.
|
|
|
|
An example of a full config is `config:base`, which is Renovate's default configuration.
|
|
It mostly uses Renovate config defaults but adds a few smart customisations such as grouping monorepo packages together.
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! note
|
|
The `:xyz` naming convention (with `:` prefix) is a special shorthand for the `default:` presets.
|
|
e.g. `:xyz` is equivalent to `default:xyz`.
|
|
|
|
## How to Use Preset Configs
|
|
|
|
By default, the Renovate App's onboarding process will suggest `["config:base]"`.
|
|
If you are self hosting you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config.
|
|
|
|
A typical onboarding `renovate.json` looks like this:
|
|
|
|
```json
|
|
{
|
|
"extends": ["config:base"]
|
|
}
|
|
```
|
|
|
|
Say you want to modify the default behavior, for example scheduling Renovate to process upgrades during non-office hours only.
|
|
To do this you can modify the default `renovate.json` file like this:
|
|
|
|
```json
|
|
{
|
|
"extends": ["config:base", "schedule:nonOfficeHours"]
|
|
}
|
|
```
|
|
|
|
This makes use of the `schedules:` presets.
|
|
You can find the Renovate team's preset configs at the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com).
|
|
|
|
## Preset Parameters
|
|
|
|
If you browse the "default" presets, you will see some that have parameters, e.g.:
|
|
|
|
```json
|
|
{
|
|
"labels": {
|
|
"description": "Apply labels <code>{{arg0}}</code> and <code>{{arg1}}</code> to PRs",
|
|
"labels": ["{{arg0}}", "{{arg1}}"]
|
|
},
|
|
"assignee": {
|
|
"description": "Assign PRs to <code>{{arg0}}</code>",
|
|
"assignees": ["{{arg0}}"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Here is how you would use these in your Renovate config:
|
|
|
|
```json
|
|
{
|
|
"extends": [":labels(dependencies,devops)", ":assignee(rarkins)"]
|
|
}
|
|
```
|
|
|
|
In short, the number of `{{argx}}` parameters in the definition is how many parameters you need to provide.
|
|
Parameters must be strings, non-quoted, and separated by commas if there are more than one.
|
|
|
|
If you find that you are repeating config a lot, you might consider publishing one of these types of parameterised presets yourself.
|
|
Or if you think your preset would be valuable for others, please contribute a PR to the Renovate repository.
|
|
|
|
## GitHub-hosted Presets
|
|
|
|
To host your preset config on GitHub:
|
|
|
|
- Create a new repository. Normally you'd call it `renovate-config` but it can be named anything
|
|
- Add configuration files to this new repo for any presets you want to share. For the default preset, `default.json` will be checked. For named presets, `<preset-name>.json` will be loaded. For example, loading preset `library` would load `library.json`. No other files are necessary.
|
|
- In other repos, reference it in an extends array like "github>owner/name", for example:
|
|
|
|
```json
|
|
{
|
|
"extends": ["github>rarkins/renovate-config"]
|
|
}
|
|
```
|
|
|
|
From then on Renovate will use the Renovate config from the preset repo's default branch.
|
|
You do not need to add it as a devDependency or add any other files to the preset repo.
|
|
|
|
## GitLab-hosted Presets
|
|
|
|
For a private GitLab repository Renovate requires at least _Reporter_ level access.
|
|
|
|
To host your preset config on GitLab:
|
|
|
|
- Create a new repository on GitLab. Normally you'd call it `renovate-config` but it can be named anything
|
|
- Add a `default.json` to this new repo containing the preset config. No other files are necessary
|
|
- In other repos, reference it in an extends array like "gitlab>owner/name", e.g. "gitlab>rarkins/renovate-config"
|
|
|
|
## Gitea-hosted Presets
|
|
|
|
To host your preset config on Gitea:
|
|
|
|
- Create a new repository on Gitea. Normally you'd call it `renovate-config` but you can use any name you want
|
|
- Add a `default.json` to this new repository containing the preset config. No other files are necessary
|
|
- In other repositories, reference it in an extends array like `"gitea>owner/name"`, e.g. `"gitea>rarkins/renovate-config"`
|
|
|
|
## Local presets
|
|
|
|
Renovate also supports local presets, e.g. presets that are hosted on the same platform as the target repository.
|
|
This is especially helpful in self-hosted scenarios where public presets cannot be used.
|
|
Local presets are specified either by leaving out any prefix, e.g. `owner/name`, or explicitly by adding a `local>` prefix, e.g. `local>owner/name`.
|
|
Renovate will determine the current platform and look up the preset from there.
|
|
|
|
## Contributing to presets
|
|
|
|
Have you configured a rule that you think others might benefit from?
|
|
Please consider contributing it to the [Renovate](https://github.com/renovatebot/renovate) repository so that it gains higher visibility and saves others from reinventing the same thing.
|
|
|
|
## Organization level presets
|
|
|
|
Whenever repository onboarding happens, Renovate checks if the current user/group/org has a default config to extend.
|
|
It looks for:
|
|
|
|
- A repository called `renovate-config` under the same user/group/org with a `default.json` file or
|
|
- A repository named like `.{{platform}}` (e.g. `.github`) under the same user/group/org with `renovate-config.json`
|
|
|
|
If found, that repository's preset will be suggested as the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden.
|
|
For example the result may be:
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
|
|
"extends": ["local>myorgname/.github:renovate-config"]
|
|
}
|
|
```
|
|
|
|
## npm-hosted presets
|
|
|
|
<!-- prettier-ignore -->
|
|
!!! warning
|
|
Using npm-hosted presets is deprecated, we recommend you do not follow these instructions and instead use a `local` preset.
|
|
|
|
If you manage multiple repositories using Renovate and want the same custom config across all or most of them, then you might want to consider publishing your own preset config so that you can "extend" it in every applicable repository.
|
|
That way when you want to change your Renovate configuration you can make the change in one location rather than having to copy/paste it to every repository individually.
|
|
|
|
Let's say that your username on npm and elsewhere is "fastcore".
|
|
In that case, you can choose between publishing your preset config package as `@fastcore/renovate-config` or `renovate-config-fastcore`.
|
|
Let's assume you choose `renovate-config-fastcore` as the package name.
|
|
|
|
You then need to publish the `renovate-config-fastcore` package where the `package.json` has the field `renovate-config` and then put your config under the field `default`.
|
|
For example:
|
|
|
|
```json
|
|
{
|
|
"name": "renovate-config-fastcore",
|
|
"version": "0.0.1",
|
|
"renovate-config": {
|
|
"default": {
|
|
"extends": ["config:base", "schedule:nonOfficeHours"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Then in each of your repositories you can add your Renovate config like:
|
|
|
|
```json
|
|
{
|
|
"extends": ["fastcore"]
|
|
}
|
|
```
|
|
|
|
Any repository including this config will then adopt the rules of the default `library` preset but schedule it on weeknights or weekends.
|
|
|
|
If you prefer to publish using the namespace `@fastcore/renovate-config` then you would use the `@` prefix instead:
|
|
|
|
```json
|
|
{
|
|
"extends": ["@fastcore"]
|
|
}
|
|
```
|