Managing Project Dependencies

Table of Contents

• Managing Dependencies
  • Renovate vs Dependabot
• Adding Renovate
  • New Projects
  • Existing Projects
  • Build Tools
  • Languages
  • Examples
• Configuring Renovate
  • Common Options
  • Dependency Dashboard
• Troubleshooting Renovate
  • Linting
  • Debugging

Managing Dependencies

As an open source project maintainer, you will inevitably become familiar with dependencies and vulnerabilities in just about any project that involves managing code, tools, containers, or packages. Of course, not all dependencies and updates are created equally — some are truly critical, like for security alerts, or a much-needed feature — while others may pile up over time, feeling more like a nuisance or chore than something that adds value to your project’s overall health. Fortunately, the open source community has developed some great tools to help manage dependencies and avoid them becoming a project maintainership headache!

Renovate vs Dependabot

Wayfair’s Open Source Program Office (OSPO) has carefully evaluated and compared the benefits of two of the more popular dependency management tools out there: GitHub’s native Dependabot, as well as Mend’s newer offering, Renovate. Although Dependabot has clear, strong benefits in terms of its fluid integration with other GitHub offerings, we have ultimately decided to support Renovate as our dependency management tool of choice, namely due to its highly-flexible customization and broader package manager ecosystem.

Renovate also integrates well with other code hosting platforms, such as GitLab and BitBucket. As an administrator of an open source organization, or the maintainer of multiple GitHub repositories, you can even create and host your own configuration presets for all of your open source projects to inherit from!

Adding Renovate

New Projects

If you’re about to begin a brand-new open source project, good news! Wayfair’s OSPO has already baked Renovate support into our Open Source Template. Feel free to use this template the next time you start a project on GitHub, and be sure to customize the included Renovate config file and linting job to your liking.

Existing Projects

If you’re the maintainer of an existing open source project, fret not! Adding Renovate is incredibly simple, especially if you don’t plan to use its advanced features and customizations right away. In fact, if you’re okay with the base configuration and default rules, it’s as simple as adding one line to a JSON file:

// renovate.json

{
  "extends": ["config:base"]
}

As you begin to learn more about Renovate’s advanced capabilities, as well as gain an understanding of your project’s language and tool-specific package management needs, you can always update your JSON configuration to accommodate your evolving needs! Better yet, there are plenty of fantastic examples of Renovate configuration files out there in the wild.

Here are some common package managers Wayfair OSPO recommends exploring:

Build Tools

• Docker ("dockerfile", "docker-compose")
• Terraform ("terraform, terragrunt")
• GitHub Actions ("github-actions")
• Buildkite ("buildkite")

Languages

• JS / Node ("npm, nvm")
• Python ("pip_requirements, pip-compile, pyenv")
• Java ("gradle, gradle-wrapper, maven")
• Swift ("swift")
• Rust ("cargo")
• Go ("gomod")
• PHP ("composer")
• .NET ("nuget, cake")

Examples

Wayfair OSPO is also proud to share several real-world projects currently using Renovate:

• Forker (GitHub Action / TypeScript)
• Aux Eng Docs (Gatsby / Node / Docker)
• wayfair.github.io (Gatsby / Node / React)
• Open Source Template (GitHub Template Repository)

Configuring Renovate

For flexibility and ease-of-use, Wayfair OSPO highly recommends configuring Renovate with repository-scoped configuration files. Put simply, for each project you wish to use Renovate with, you should commit a renovate.json (or similar) file to the repository root. If your repository’s code is hosted on GitHub, you should be able to install the Renovate GitHub App on any repositories you maintain. If your repository is hosted on a separate GitHub organization, you can request that your org administrator install Renovate, with permissions scoped to either select repositories or all repositories.

If you are unable to leverage GitHub hosting, or prefer to self-host your instance of Renovate, refer to the following docs:

• Getting Started
• Self-Hosting Examples
• Configuration Options
• Experimental Options
• Getting Logs

Common Options

While Renovate offers numerous customizations, a few key options provide immediate value to project maintainers without requiring too much tweaking:

• Scheduling:

  "schedule": [
    "before 3am every weekday" // Runs daily before 3:00 AM UTC
  ]

• Package Managers:

  "enabledManagers": [ // Manages packages for Docker, GitHub, Node
    "dockerfile",
    "docker-compose",
    "github-actions",
    "npm"
  ]

• Batch Updates:

  "packageRules": [ // Group packages for Gatsby, React, Docker, GitHub
    {
      "matchPackageNames": ["gatsby"],
      "matchPackagePrefixes": ["gatsby-"],
      "groupName": "Gatsby"
    },
    {
      "matchPackageNames": ["react"],
      "matchPackagePrefixes": ["react-"],
      "groupName": "React"
    },
    {
      "matchManagers": ["dockerfile", "docker-compose"],
      "groupName": "Docker"
    },
    {
      "matchManagers": ["github-actions"],
      "groupName": "GitHub Actions"
    }
  ]

• Automerging:

  "packageRules": [ // Only automerge minor package updates
    {
      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
      "groupName": "Minor Packages",
      "automerge": true
    },
  ]

• Config Presets:

  "extends": [ // Extends base config, enables dashboard, rebases PRs
    "config:base",
    ":dependencyDashboard",
    ":rebaseStalePrs"
  ]

Dependency Dashboard

Once configured on GitHub or GitLab, Renovate will maintain overall state of your project’s dependencies through a dedicated issue titled “Dependency Dashboard,” filed by the renovate bot user. The Renovate Dependency Dashboard utilizes dynamic Markdown checkboxes to allow project maintainers to interact directly with the issue content.

You can use these interactive checkboxes to do things like manually force Renovate to run (eg. outside of its normal schedule), or retry a previously-attempted update. You can even customize your dashboard to create custom approval workflows for specific packages or major updates.

Better yet, by enabling Renovate as a GitHub-hosted app, you’ll be able to view Renovate logs for all of your repos across all organizations by navigating to:

# Replace <ORG_NAME> and <REPO_NAME> as appropriate:

https://app.renovatebot.com/dashboard#github/<ORG_NAME>/<REPO_NAME>

💡 If you’ve already committed a valid renovate.json configuration file to your project, and still don’t see a Dependency Dashboard issue automatically filed / updated according to your specified schedule, make sure the Renovate App and renovate bot user have been granted access to your repository. If you are the administrator of a GitHub organization, you can optionally enable the Renovate App for all repositories, allowing for more seamless monitoring of Renovate installations across your org.

Troubleshooting Renovate

Linting

As your Renovate configuration becomes more complex and nuanced, you’ll want to ensure any changes you make won’t break the existing settings. If you’re already using GitHub Workflows for your project’s CI, you can simply add a new linting job to which leverages the renovate-config-validator GitHub Action:

# lint.yml

jobs:
  renovate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 🧼 lint renovate config # Validates changes to renovate.json config file
        uses: suzuki-shunsuke/github-action-renovate-config-validator@v0.1.2
        with:
          config_file_path: 'renovate.json'

💡 If you’re using (or planning to use) Wayfair’s Open Source Template to kickstart your project, the provided lint.yml workflow file already includes this step!

Debugging

Once you’ve configured and validated Renovate, you may still experience issues and unexpected behaviors. This is where debug logs become crucial to navigating problems with Renovate. Fortunately, it’s easy to access these logs on the Renovate App Dashboard if you’ve installed Renovate as a GitHub-hosted app. If you’ve gone the self-hosted route, there’s separate guidance for accessing logs on your own instance.

💡 If you’re using the Renovate App Dashboard for log viewing, ensure you’ve first authenticated with your desired GitHub / GitLab account. Once logged in, you should be able to view logs (up to 3 days old) for all Renovate-enabled repositories you have access to.

🧹 Happy renovating!