iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🤖

Renovate Automerge Configuration Guide: Automating Dependency Updates

に公開
GitHub
自動化
CI/CD
DevOps
Renovate
tech

Introduction

Dependency update tasks are essential for maintaining application security and quality, but doing them manually is a significant burden. With Renovate, you can automate dependency updates, and you can further increase efficiency by utilizing the auto-merge feature.

In this article, I will explain how to set up Renovate's auto-merge step-by-step. It covers practical content, ranging from GitHub branch protection settings and CI/CD integration to best practices for safe operation.

What you can learn in this article

  • Basics and configuration of Renovate's auto-merge feature
  • Proper configuration of GitHub repositories and branch protection rules
  • Integration with CI/CD
  • Troubleshooting and solutions
  • Best practices for safe operation

Target Audience

  • Those who have already introduced Renovate and are considering auto-merge
  • Developers interested in automating dependency management
  • Those with a basic understanding of Git/GitHub operations and CI/CD basics

What is Renovate?

Renovate is a tool that automates dependency updates. It supports various package managers such as package.json, Gemfile, and pom.xml, and automatically creates Pull Requests when new versions are released.

Benefits of Auto-merge

  • Reduction in working time: Automate the review and merging of minor updates
  • Timely updates: Security patches are applied immediately
  • Preventing PR accumulation: Prevents the accumulation of PRs waiting for manual merging

Risks and Countermeasures of Auto-merge

On the other hand, auto-merge also carries risks:

  • Introduction of breaking changes: Potential for compatibility loss in major version updates
  • Inclusion of bugs: Potential for unexpected bugs in new versions

These risks can be mitigated through proper configuration and automated testing with CI/CD. This article explains safe configuration methods in detail.

Prerequisites

Before setting up Renovate's auto-merge, ensure that you have the following ready:

  • GitHub Repository: Admin access to the target repository
  • CI/CD Configuration: An environment where automated tests are executed (e.g., GitHub Actions)
  • Test Coverage: Tests capable of detecting regressions caused by dependency updates

Step 1: Installing Renovate

First, install Renovate into your GitHub repository.

1-1. Installing the GitHub App

  1. Access the Renovate GitHub App.
  2. Click "Install" or "Configure".
  3. Select the account to install it to (Personal or Organization).
  4. Choose the repositories (all repositories or specific ones).
  5. Click "Install" to authorize the permissions.

1-2. Confirming the Initial Run

After installation, Renovate will run automatically and create an Onboarding PR.

This PR includes:

  • The initial renovate.json configuration file.
  • A list of detected dependencies.
  • An explanation of how Renovate operates.

Once you merge the Onboarding PR, Renovate will begin its full operation.

Step 2: Basic Configuration of renovate.json

Renovate configuration is managed via renovate.json placed at the root of the repository.

2-1. Basic Settings

Once the Onboarding PR is merged, a basic configuration like the following is created:

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

config:recommended is Renovate's recommended configuration preset. This includes:

  • Periodic checks for dependencies
  • Updates based on semantic versioning
  • Basic settings for grouping and scheduling

2-2. Verifying the Operation

Once the configuration is merged, Renovate will automatically scan the dependencies and create PRs if there are any packages that can be updated.

Step 3: Configuring Auto-merge

This is the most important step. Add the auto-merge configuration to renovate.json.

3-1. Basic Auto-merge Configuration

First, let's start with the safest configuration, which only auto-merges patch updates:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "automerge": true
    }
  ],
  "platformAutomerge": true
}

3-2. Explanation of Configuration Items

  • packageRules: Defines rules per package
  • matchUpdateTypes: Specifies the types of updates to be merged
    • "patch": Patch versions (1.2.3 → 1.2.4)
    • "minor": Minor versions (1.2.3 → 1.3.0)
    • "major": Major versions (1.2.3 → 2.0.0)
  • automerge: Enables auto-merge (set to true to enable)
  • platformAutomerge: Uses GitHub's native auto-merge feature

3-3. Advanced Configuration Patterns

Pattern 1: Auto-merge patch and minor updates

{
  "packageRules": [
    {
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    }
  ],
  "platformAutomerge": true
}

Pattern 2: Auto-merge devDependencies only

{
  "packageRules": [
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    }
  ],
  "platformAutomerge": true
}

Pattern 3: Auto-merge specific packages only

{
  "packageRules": [
    {
      "matchPackageNames": ["lodash", "axios"],
      "matchUpdateTypes": ["patch"],
      "automerge": true
    }
  ],
  "platformAutomerge": true
}

Pattern 4: Auto-merge TypeScript type definitions

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^@types/"],
      "automerge": true
    }
  ],
  "platformAutomerge": true
}

Step 4: GitHub Repository Settings

You need to enable auto-merge on the GitHub side.

4-1. Enabling "Allow auto-merge"

  1. Open the repository Settings.
  2. Select General from the left menu.
  3. Scroll down to the Pull Requests section.
  4. Check Allow auto-merge.
  5. (Recommended) Also check Automatically delete head branches.

Step 5: Branch Protection Rule Settings

Branch protection is the most important setting for auto-merge. This ensures that only PRs with successful CI are merged.

5-1. Adding Branch Protection Rules

  1. Open the repository Settings.
  2. Select Branches from the left menu.
  3. Click Add rule under Branch protection rules.
  4. Enter main (or the branch name you want to protect) in the Branch name pattern.

5-2. Required Configuration Items

Enable the following settings:

✅ Require a pull request before merging

Enable this to prevent direct pushes to the branch.

✅ Require status checks to pass before merging

This is the most important setting. Enable this and also configure the following:

  • Require branches to be up to date before merging: Check this.
  • Status checks that are required: Make sure to select at least one CI job.
  • Require linear history: Enable this if you want to avoid merge commits.
  • Do not allow bypassing the above settings: If more strict protection is required.

Once the settings are complete, click Create or Save changes.

Step 6: Integration with CI/CD

To operate auto-merge safely, running tests in CI is mandatory.

6-1. Configuration Example for GitHub Actions

Create .github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linter
        run: npm run lint
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build

6-2. Key Points for CI

  • Use npm ci: Faster than npm install and ensures installation strictly according to package-lock.json.
  • Always run lint and test: Checks both code quality and functionality.
  • Run build: Confirms there are no build errors.

6-3. Verifying Status Checks

After configuring CI, create a PR and verify the following:

  1. CI is triggered automatically
  2. "All checks have passed" is displayed at the bottom of the PR
  3. The job name configured in the branch protection rules is displayed

Step 7: Verifying the Operation

Once all settings are complete, perform an actual verification.

7-1. Updating Dependencies for Testing

Manually downgrade a dependency to an older version and wait for Renovate to create a PR.

Alternatively, you can run it immediately without waiting for the Renovate schedule using the following method:

  1. Open the Issues tab of the repository.
  2. Look for the Issue created by Renovate (usually titled "Dependency Dashboard").
  3. Click the checkbox to manually trigger a specific update.

7-2. Confirming Auto-merge

Verify the following in the PR created by Renovate:

  1. PR is automatically created: PR creation by Renovate.
  2. CI is executed: GitHub Actions is automatically triggered.
  3. CI succeeds: All checks turn green.
  4. Automatically merged: The PR is automatically merged after a few minutes.

7-3. Verification After Merge

Once the auto-merge is successful:

  • The PR is closed.
  • The branch is deleted (if automatic deletion is enabled).
  • Changes are merged into the main branch.

Advanced Configuration

Once basic auto-merge is working, let's try more advanced settings.

Schedule Settings

By executing auto-merge outside of business hours, you can minimize the impact if problems occur.

{
  "schedule": ["after 10pm every weekday", "before 5am every weekday"],
  "timezone": "Asia/Tokyo",
  "automergeSchedule": ["after 10pm every weekday", "before 5am every weekday"]
}
  • schedule: Timing for Renovate to create PRs
  • automergeSchedule: Timing to execute auto-merge
  • timezone: Specification of the time zone

Grouping Settings

By grouping related dependencies into a single PR, you can streamline review and merging.

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^@types/"],
      "groupName": "TypeScript type definitions",
      "automerge": true
    },
    {
      "matchPackagePatterns": ["^eslint"],
      "groupName": "ESLint packages",
      "automerge": true
    }
  ]
}

PR Limit Settings

Limit the number of PRs created at once to make them easier to manage.

{
  "prConcurrentLimit": 5,
  "prHourlyLimit": 2
}

Troubleshooting

Here are some ways to handle cases where auto-merge does not work.

Issue 1: "Auto-merge is not available"

Symptoms: The PR displays "Auto-merge is not available for this pull request."

Causes:

  • "Allow auto-merge" is disabled in the repository settings.
  • It is disabled in the Organization settings.

Solution:

  1. Check Settings > General > Pull Requests and verify "Allow auto-merge".
  2. In the case of an Organization, also check the Organization settings.

Issue 2: "Required status check is missing"

Symptoms: The PR is not merged, or status checks are not displayed.

Causes:

  • No status checks are selected in the branch protection rules.
  • The CI job name is incorrect.

Solution:

  1. Check Settings > Branches > Branch protection rules.
  2. Verify if "Require status checks to pass before merging" is enabled.
  3. Verify if specific status checks (CI job names) are selected.
  4. Check the job name in the CI workflow file (e.g., jobs: test:).

Issue 3: CI Fails

Symptoms: CI always fails on Renovate's PRs.

Causes:

  • Compatibility issues with the new version.
  • Tests assume a specific version of a dependency.

Solution:

  1. Check the CI logs in the PR to identify the error.
  2. Reproduce it locally by updating the dependency.
  3. Fix the code or the test.
  4. Add a setting to exclude it from auto-merge:
{
  "packageRules": [
    {
      "matchPackageNames": ["problematic-package-name"],
      "automerge": false
    }
  ]
}

Issue 4: Auto-merge is Slow

Symptoms: It takes a long time to merge even after the CI succeeds.

Causes:

  • Delays in GitHub's internal processing.
  • Other PRs are being processed.
  • The branch is not up to date.

Solution:

  • Usually, just waiting will solve it (about 5–10 minutes).
  • If it hasn't been merged for a long time, update the branch manually.
  • Add rebaseWhen: "behind-base-branch" to the Renovate configuration.

Checklist

If auto-merge is not working, please check the following in order:

  • "automerge": true is set in renovate.json.
  • "platformAutomerge": true is set in renovate.json.
  • "Allow auto-merge" is enabled in the repository settings.
  • Branch protection rules are configured.
  • Specific status checks are selected in the branch protection rules.
  • CI is running normally and succeeding.
  • The PR matches the target update type (e.g., patch).

Best Practices for Operation

Here are the best practices for operating auto-merge safely and efficiently.

Gradual Introduction

It is dangerous to auto-merge all updates all at once. Let's introduce it gradually in the following order:

Phase 1: Patch updates only (Safest)

{
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "automerge": true
    }
  ]
}

Operate for 1 to 2 weeks and confirm that there are no problems.

Phase 2: Add minor updates

{
  "packageRules": [
    {
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    }
  ]
}

Operate for another 1 to 2 weeks.

Phase 3: Add devDependencies

{
  "packageRules": [
    {
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["major"],
      "automerge": true
    }
  ]
}

Since devDependencies do not affect the production environment, you can also auto-merge major updates for them.

Phase 4: Add major updates for specific packages (Optional)

{
  "packageRules": [
    {
      "matchPackageNames": ["stable-package-name"],
      "automerge": true
    }
  ]
}

Auto-merge major updates only for packages that have been stable for a long time.

Security Considerations

1. Ensure test coverage

The safety of auto-merge directly depends on the quality of your tests:

  • Aim for at least 70% or higher code coverage
  • Always write tests for critical functions
  • Verify actual behavior with E2E tests

2. Prioritize security updates

{
  "vulnerabilityAlerts": {
    "enabled": true
  },
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "matchDepTypes": ["dependencies"],
      "automerge": true
    }
  ]
}

Renovate prioritizes security updates automatically, but you should actively auto-merge patch updates, especially for dependencies.

3. Manual review for important dependencies

We recommend excluding dependencies like the following from auto-merge:

  • Core frameworks (React, Vue.js, etc.)
  • Database drivers
  • Authentication libraries
  • Payment processing related
{
  "packageRules": [
    {
      "matchPackageNames": ["react", "react-dom", "prisma"],
      "automerge": false
    }
  ]
}

Points to Note in Team Operation

1. Agree on the scope of auto-merge as a team

Decide the following as a whole team:

  • Which update types to auto-merge (patch, minor, major)
  • Which dependencies to target (dependencies, devDependencies)
  • Which packages to exclude

2. Adjustment of notification settings

If there are too many Renovate PRs and notifications are annoying:

{
  "assignees": ["@team-name"],
  "reviewers": [],
  "suppressNotifications": ["prIgnoreNotification"]
}

You can suppress notifications for PRs that are auto-merged.

3. Utilization of Dependency Dashboard

Utilize the "Dependency Dashboard" Issue created by Renovate:

  • All pending updates are listed
  • You can manually trigger updates
  • You can check PRs where errors occurred

Monitoring and Improvement

1. Regular review of settings

Check the following once a month:

  • Success rate of auto-merge
  • Failure rate of CI
  • Number of manual rollbacks

2. Analysis of failure patterns

When a problem occurs with auto-merge:

  • Record which package caused the issue
  • Consider whether to exclude that package from auto-merge
  • Add tests to be able to detect the same issue

3. Feedback to the team

Regularly share the operation status of auto-merge with the team:

  • Number of auto-merges this month
  • Work time saved
  • Problems encountered and how they were handled

Summary

I have explained Renovate's auto-merge settings step-by-step.

Key Points

  • Gradual Introduction: Start with patches and gradually expand the scope
  • CI/CD Readiness: Automated tests ensure the safety of auto-merge
  • Branch Protection Settings: It is mandatory to specifically select status checks
  • Utilizing platformAutomerge: Make it safer with GitHub's native features
  • Team Agreement: Decide the scope of auto-merge as a whole team

Next Actions

  1. Today: Install Renovate and perform basic configuration
  2. This Week: Add settings to auto-merge patch updates only
  3. Next Month: Check the operation status and consider auto-merging minor updates
  4. Ongoing: Regularly review settings and provide feedback to the team

By utilizing Renovate's auto-merge, you can significantly reduce dependency update work and focus more on important development tasks. Start with a safe scope and gradually expand the range of automation.

Discussion