Skip to content

Commit

Permalink
docs: improve key concepts automerge (#11639)
Browse files Browse the repository at this point in the history
  • Loading branch information
HonkingGoose committed Sep 8, 2021
1 parent 357068d commit 11577d6
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions docs/usage/key-concepts/automerge.md
Expand Up @@ -5,17 +5,17 @@ description: Learn all about Renovate's automerge functionality here

# Introduction

Automerging is a Renovate feature that can enable you to fully automate upgrading of certain dependencies.
When enabled, it means Renovate will attempt to merge the proposed update once it has passed tests.
Automerging is a Renovate feature that you can use to automate upgrading dependencies.
When enabled, Renovate will attempt to merge the proposed update once the tests pass.

As a general guide, it is recommended that you enable automerge for any types of dependency updates where you would just click Merge anyway.
If there are updates for which you prefer to manually review release notes or code before merging, even when they pass tests, then do not enable automerge for those.
As a general guide, we recommend that you enable automerge for any type of dependency updates where you would just click "merge" anyway.
For any updates where you want to review the release notes - or code - before you merge, you can keep automerge disabled.

Automerge works particularly well for `devDependencies` as well as for production `dependencies` in projects which have great test coverage.

For example, if you have `jest` or `mocha` as a dependency, and it has an upgrade with passing tests... automerge them!
If you have a linter like `eslint` or `tslint` and its update passes... automerge them!
If you have an API with 100% test coverage and `express` is updated... automerge it!
For example, if you have Jest or Mocha as a development dependency, and it has an upgrade with passing tests... automerge them!
If you have a linter like ESLint or TSLint and its update passes... automerge them!
If you have an API with 100% test coverage and Express is updated... automerge it!

![Automerged PR](/assets/images/automerged-pr.png)

Expand All @@ -39,7 +39,7 @@ Here is an example of automerging lock file maintenance:
### Automerge lint tool updates

Automerging lint tool updates can be a real time-saver.
Sometimes an update to a lint tool or plugin definition can cause tests to fail, and that is usually deliberate/intentional because the lint authors have added a new rule that you need to adhere to.
Sometimes an update to a lint tool or plugin definition causes tests to fail, and that is usually deliberate/intentional because the lint authors have added a new rule that you need to adhere to.
However, in many cases the new version(s) will pass tests, and if so then there's really nothing else to consider before merging, so they may as well be automerged:

```json
Expand Down Expand Up @@ -75,12 +75,12 @@ The `matchCurrentVersion` setting above is a rule to exclude any dependencies wh
## Automerging and scheduling

Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates.
And this is especially so if your repository needs rebasing, e.g. because you use lock files.
e.g. let's say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file.
And this is especially so if your repository needs rebasing, like when you use lock files.
Let's say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file.

- At the start of the schedule, `Renovate` will create branches for `abc` and `xyz` upgrades, including `yarn.lock` updates
- After `abc` passes tests, `Renovate` will automerge it into the base branch
- The `xyz` branch probably now has `yarn.lock` conflicts
- The `xyz` branch has a `yarn.lock` conflict now
- Renovate will immediately check all other branches and rebase them
- The change to `xyz` branch will trigger another round of CI tests
- After the updated `xyz` branch passes, Renovate will automerge it too
Expand All @@ -98,21 +98,21 @@ For this reason we recommend you consider setting `automergeType=branch` which w

Add the `renovate/**` branch to your testing workflow files, or Renovate will not work properly with the `automergeType=branch` setting.

The result is that passing updates are essentially "silent" - the only sign of them are the commits to your base branch.
The result is that passing updates are essentially "silent" - the only sign of them are the commits Renovate pushes to your base branch.
If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won't work and you should stick with the default PR-based automerging instead.

## Assignees and Reviewers

When automerge is enabled on a PR, Renovate will _not_ add assignees or reviewers at PR creation time, in order to decrease notifications noise a little.
If tests subsequently _fail_, making automerge not possible, then Renovate will then add the configured assignees and/or reviewers.
If tests subsequently _fail_, making automerge not possible, then Renovate will add the configured assignees and/or reviewers.

## Frequent problems and how to resolve them

### Automerge not enabled correctly in config

Sometimes, the reason Renovate is not automerging a PR is because of a configuration mistake.
You can confirm that Renovate knows you want it to automerge by checking if the PR body includes the text "Automerge: Enabled".
If you see "Automerge: Disabled by config" then it means you need a config change for automerge to work.
If you see "Automerge: Disabled by config" it means you need to make a config change for automerge to work.

### Absence of tests

Expand Down

0 comments on commit 11577d6

Please sign in to comment.