📘 Renovate Configuration for Flutter with Bitbucket - dhruvin207/flutter-common-utils GitHub Wiki

🛠️ Why This Guide?

During the process of integrating Renovate for Flutter projects hosted on Bitbucket, I noticed a significant lack of clear and detailed documentation online. There were no step-by-step examples or comprehensive explanations to simplify the setup. This guide was created to fill that gap and provide a complete, professional, and easy-to-follow resource for developers.

The goal of this guide is to help you configure Renovate to automate dependency updates in Flutter projects by generating pull requests (PRs) whenever a new package version is available. Let's make keeping your Flutter dependencies up-to-date simple and effortless!

📋 Introduction to Renovate

Renovate is a powerful open-source tool that automates the process of updating dependencies in your projects. By generating PRs for package updates, it helps you:

  • Avoid technical debt.
  • Keep dependencies secure and up-to-date.
  • Save time and reduce manual effort in managing packages.

For Flutter projects, Renovate can track updates to Dart packages, Flutter SDK versions, and other critical dependencies in your pubspec.yaml.

📦 Prerequisites

Before setting up Renovate, ensure you have:

  1. Admin access to the Bitbucket repository.
  2. Environment variables configured in your repository:
    • RENOVATE_USERNAME: Your Renovate bot username.
    • RENOVATE_PASSWORD: Your Renovate bot password.
    • RENOVATE_USER_EMAIL: Email associated with the Renovate bot.
    • RENOVATE_GITHUB_TOKEN: A GitHub token for accessing dependencies.
  3. A basic understanding of Bitbucket pipelines.

🏗️ Configuring Renovate

1️⃣ Bitbucket Pipeline Setup

Add the following configuration to your bitbucket-pipelines.yml file:

image: atlassian/default-image:latest 
definitions:
  steps:
    renovate: &renovate-step
      step:
        name: Renovate-scan
        script:
          - pipe: atlassian/renovate-scan:0.8.0
            variables:
              RENOVATE_USERNAME: $RENOVATE_USERNAME
              RENOVATE_PASSWORD: $RENOVATE_PASSWORD
              RENOVATE_USER_EMAIL: $RENOVATE_USER_EMAIL
              GITHUB_COM_TOKEN: $RENOVATE_GITHUB_TOKEN
              CONFIG_FILE_PATH: "./renovate.json"
              DEBUG: "true"
pipelines:
  custom:
    renovate-scan:
      - <<: *renovate-step

🔍 Explanation

  • image: atlassian/default-image:latest: Specifies the Docker image used for the pipeline.
  • pipe: atlassian/renovate-scan:0.8.0: The Renovate scan pipe provided by Atlassian.
  • Variables: Environment variables provide the credentials and specify the path to the Renovate configuration file.
  • DEBUG: "true": Enables detailed logging for debugging purposes.

📝 Triggering the Pipeline

This pipeline is set up as a custom pipeline, which means you need to trigger it manually from the Bitbucket interface or via API calls.

2️⃣ Renovate Configuration File

Add a renovate.json file to the root of your repository with the following content:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "platform": "bitbucket",
  "repositories": ["your-org/your-repo"],
  "onboarding": true,
  "baseBranches": ["Dev"],
  "branchPrefix": "renovate/",
  "extends": ["config:recommended"],
  "rangeStrategy": "bump",
  "versioning": "semver",
  "rebaseWhen": "behind-base-branch",
  "semanticCommits": "disabled",
  "commitMessageAction": "Upgrade",
  "commitMessageExtra": "from {{currentValue}} to {{newValue}}",
  "separateMajorMinor": false,
  "prHourlyLimit": 0,
  "prConcurrentLimit": 0,
  "prNotPendingHours": 0,
  "enabledManagers": ["pub"],
  "automerge": false,
  "packageRules": [
    {
      "matchManagers": ["pub"],
      "enabled": true,
      "matchPackageNames": ["flutter", "dart"],
      "matchDatasources": ["dart-version", "flutter-version"],
      "prPriority": 1,
      "groupName": "Flutter SDK"
    },
    {
      "matchManagers": ["pub"],
      "enabled": true,
      "matchPackageNames": ["firebase_**"],
      "prPriority": 2,
      "groupName": "Firebase Packages"
    },
    {
      "matchManagers": ["pub"],
      "enabled": true,
      "matchPackageNames": ["purchases_**"],
      "prPriority": 3,
      "groupName": "Purchases Packages"
    },
    {
      "matchManagers": ["pub"],
      "enabled": true,
      "commitMessageTopic": "package {{depName}}",
      "prPriority": 4
    }
  ],
  "ignoreTests": true,
  "ignoreScripts": true,
  "skipInstalls": true,
  "updateLockFiles": false,
  "lockFileMaintenance": {
    "enabled": false
  },
  "ignorePaths": [
    "**/pubspec.lock",
    "*/.lock",
    "*/build/*"
  ]
}

📘 Detailed Explanation of renovate.json

🔗 General Configuration

  • platform: Specifies the target platform (bitbucket).
  • repositories: Lists the repositories to configure Renovate for.
  • onboarding: If true, creates an onboarding PR with the initial configuration.
  • baseBranches: Defines the branches Renovate will target for PRs (e.g., Dev).
  • branchPrefix: Adds a prefix to Renovate-created branches (e.g., renovate/).

📈 Dependency Update Strategies

  • rangeStrategy: Specifies the update strategy. "bump" ensures minimal version increments.
  • versioning: Defines the versioning system. "semver" ensures semantic versioning.
  • rebaseWhen: Rebases the PR if the base branch has moved ahead.

✏️ Commit and PR Customization

  • semanticCommits: Enables or disables semantic commit messages.
  • commitMessageAction & commitMessageExtra: Customize commit messages.

🚀 Managers and Rules

  • enabledManagers: Specifies dependency managers to scan (pub for Flutter).
  • packageRules:
    • Groups and prioritizes updates based on package names.
    • Example groups:
      • Flutter SDK (flutter and dart).
      • Firebase packages (firebase_**).
      • Purchases packages (purchases_**).

⚙️ Maintenance and Ignored Paths

  • ignoreTests, ignoreScripts, skipInstalls: Skips unnecessary steps during updates.
  • updateLockFiles: Disabled for Flutter as it does not rely on lock file updates.
  • ignorePaths: Excludes specific paths like pubspec.lock and build directories.

🌟 Workflow Overview

  1. Pipeline Trigger: The pipeline executes Renovate.
  2. Dependency Scan: Renovate scans pubspec.yaml to identify updates.
  3. Pull Request Creation:
    • Separate PRs are created for each group based on packageRules.
  4. Review and Merge:
    • Review the PRs, run tests, and merge the changes.

🔗 Useful Resources

📝 Notes

  • Place the renovate.json file in the root of your repository.
  • Test your setup in a development branch before applying it to production.
  • Customize packageRules to suit the needs of your Flutter project.

By following this guide, you’ll be able to seamlessly automate dependency updates for your Flutter project hosted on Bitbucket, ensuring it remains secure and up-to-date. 🎉