From a65c151ed3789cea92876de1843fd1ba82e810ef Mon Sep 17 00:00:00 2001 From: Anne-Marie <102995847+am-stead@users.noreply.github.com> Date: Thu, 29 Jun 2023 22:52:55 +0200 Subject: [PATCH] [2023-06-29]: Dependabot Grouped Updates - [Public Beta] #10346 (#38230) Co-authored-by: Caro Galvin Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com> Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com> --- .../about-dependabot-version-updates.md | 2 +- ...ion-options-for-the-dependabot.yml-file.md | 30 +++++++++++++- .../customizing-dependency-updates.md | 19 ++++++++- ...ng-pull-requests-for-dependency-updates.md | 8 +++- .../troubleshooting-dependabot-errors.md | 40 +++++++++++++++++++ .../dependabot-version-updates-groups.yml | 6 +++ .../dependabot/configuration-options.md | 3 +- ...dependabot-version-updates-groups-about.md | 1 + .../dependabot-version-updates-groups-beta.md | 9 +++++ ...ndabot-version-updates-groups-supported.md | 1 + ...bot-version-updates-groups-yaml-example.md | 28 +++++++++++++ data/reusables/dependabot/initial-updates.md | 2 + 12 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 data/features/dependabot-version-updates-groups.yml create mode 100644 data/reusables/dependabot/dependabot-version-updates-groups-about.md create mode 100644 data/reusables/dependabot/dependabot-version-updates-groups-beta.md create mode 100644 data/reusables/dependabot/dependabot-version-updates-groups-supported.md create mode 100644 data/reusables/dependabot/dependabot-version-updates-groups-yaml-example.md diff --git a/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md b/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md index fe2c4a29e0..5d00fe3935 100644 --- a/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md +++ b/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md @@ -47,7 +47,7 @@ If you enable _security updates_, {% data variables.product.prodname_dependabot You specify how often to check each ecosystem for new versions in the configuration file: daily, weekly, or monthly. -{% data reusables.dependabot.initial-updates %} +{% data reusables.dependabot.initial-updates %} For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates)." If you've enabled security updates, you'll sometimes see extra pull requests for security updates. These are triggered by a {% data variables.product.prodname_dependabot %} alert for a dependency on your default branch. {% data variables.product.prodname_dependabot %} automatically raises a pull request to update the vulnerable dependency. diff --git a/content/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file.md b/content/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file.md index 55690ff1e6..a1c71aa109 100644 --- a/content/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file.md +++ b/content/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file.md @@ -50,7 +50,7 @@ These options fit broadly into the following categories. - Essential set up options that you must include in all configurations: [`package-ecosystem`](#package-ecosystem), [`directory`](#directory),[`schedule.interval`](#scheduleinterval). - Options to customize the update schedule: [`schedule.time`](#scheduletime), [`schedule.timezone`](#scheduletimezone), [`schedule.day`](#scheduleday). -- Options to control which dependencies are updated: [`allow`](#allow), [`ignore`](#ignore), [`vendor`](#vendor). +- Options to control which dependencies are updated: [`allow`](#allow), {% ifversion dependabot-version-updates-groups %}[`groups`](#groups),{% endif %} [`ignore`](#ignore), [`vendor`](#vendor). - Options to add metadata to pull requests: [`reviewers`](#reviewers), [`assignees`](#assignees), [`labels`](#labels), [`milestone`](#milestone). - Options to change the behavior of the pull requests: [`target-branch`](#target-branch), [`versioning-strategy`](#versioning-strategy), [`commit-message`](#commit-message), [`rebase-strategy`](#rebase-strategy), [`pull-request-branch-name.separator`](#pull-request-branch-nameseparator). @@ -326,6 +326,34 @@ If you use the same configuration as in the example above, bumping the `requests `pip dev: bump requests from 1.0.0 to 1.0.1` +{% ifversion dependabot-version-updates-groups %} +### `groups` + +{% data reusables.dependabot.dependabot-version-updates-groups-beta %} + +{% data reusables.dependabot.dependabot-version-updates-groups-about %} + +{% data reusables.dependabot.dependabot-version-updates-groups-supported %} + +When you first configure a group, you specify a group name that will display in pull request titles and branch names. In the example below, the name of the group is `dev-dependencies`. + +You then define `patterns` (strings of characters) that match with a dependency name (or multiple dependency names) to include those dependencies in the group. + +If a dependency doesn't belong to any group, {% data variables.product.prodname_dependabot %} will continue to raise single pull requests to update the dependency to its latest version as normal. + +You can also use `exclude-patterns` to exclude certain dependencies from the group. If a dependency is excluded from a group, {% data variables.product.prodname_dependabot %} will continue to raise single pull requests to update the dependency to its latest version. + +Note that you can't use `@dependabot ignore` with pull requests for grouped updates. If you want to ignore version updates for a dependency, you must configure an [`ignore`](#ignore) rule for the dependency in the `dependabot.yml` file. + +When a scheduled update runs, {% data variables.product.prodname_dependabot %} will refresh pull requests for grouped updates using the following rules: +- if all the same dependencies need to be updated to the same versions, {% data variables.product.prodname_dependabot %} will rebase the branch. +- if all the same dependencies need to be updated, but a newer version has become available for one (or more) of the dependencies, {% data variables.product.prodname_dependabot %} will close the pull request and create a new one. +- if the dependencies to be updated have changed - for example, if another dependency in the group now has an update available - {% data variables.product.prodname_dependabot %} will close the pull request and create a new one. + +{% data reusables.dependabot.dependabot-version-updates-groups-yaml-example %} + +{% endif %} + ### `ignore` {% data reusables.dependabot.default-dependencies-allow-ignore %} diff --git a/content/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates.md b/content/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates.md index d312d039c1..809720b09c 100644 --- a/content/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates.md +++ b/content/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates.md @@ -30,7 +30,8 @@ shortTitle: Customize updates After you've enabled version updates, you can customize how {% data variables.product.prodname_dependabot %} maintains your dependencies by adding further options to the _dependabot.yml_ file. For example, you could: - Specify which day of the week to open pull requests for version updates: `schedule.day` -- Set reviewers, assignees, and labels for each package manager: `reviewers`, `assignees`, and `labels` +- Set reviewers, assignees, and labels for each package manager: `reviewers`, `assignees`, and `labels`{%- ifversion dependabot-version-updates-groups %} +- Create groups of dependencies (per package ecosystem), so that {% data variables.product.prodname_dependabot %} updates the group of dependencies in a single pull request: `groups`{% endif %} - Define a versioning strategy for changes to each manifest file: `versioning-strategy` - Change the maximum number of open pull requests for version updates from the default of 5: `open-pull-requests-limit` - Open pull requests for version updates to target a specific branch, instead of the default branch: `target-branch` @@ -138,6 +139,22 @@ updates: - "Docker dependencies" - "triage-board" ``` +{% ifversion dependabot-version-updates-groups %} +## Grouping {% data variables.product.prodname_dependabot_version_updates %} into one pull request + +{% data reusables.dependabot.dependabot-version-updates-groups-beta %} + +{% data reusables.dependabot.dependabot-version-updates-groups-about %} + +{% data reusables.dependabot.dependabot-version-updates-groups-supported %} + +The example `dependabot.yml` file changes the bundler configuration to create a group of dependencies. The configuration specifies `patterns` (strings of characters) that match with the name of a dependency (or multiple dependencies) in order to include the dependencies in the group. You can also use `exclude-patterns` to exclude a dependency (or multiple dependencies) from the group. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups)." + +You must configure groups per package ecosystem. + +{% data reusables.dependabot.dependabot-version-updates-groups-yaml-example %} + +{% endif %} ## More examples diff --git a/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md b/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md index 69e80280fb..862281b3d8 100644 --- a/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md +++ b/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md @@ -30,7 +30,7 @@ shortTitle: Manage Dependabot PRs When {% data variables.product.prodname_dependabot %} raises a pull request, you're notified by your chosen method for the repository. Each pull request contains detailed information about the proposed change, taken from the package manager. These pull requests follow the normal checks and tests defined in your repository. {% ifversion fpt or ghec %}In addition, where enough information is available, you'll see a compatibility score. This may also help you decide whether or not to merge the change. For information about this score, see "[AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)."{% endif %} -If you have many dependencies to manage, you may want to customize the configuration for each package manager so that pull requests have specific reviewers, assignees, and labels. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates)." +If you have many dependencies to manage, you may want to customize the configuration for each package manager so that pull requests have specific reviewers, assignees, and labels. {% ifversion dependabot-version-updates-groups %} You may also want to group sets of dependencies together, so that multiple dependencies are updated in a single pull request.{% endif %} For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependency-updates)." {% ifversion dependabot-updates-paused %} @@ -77,4 +77,8 @@ You can use any of the following commands on a {% data variables.product.prodnam {% data variables.product.prodname_dependabot %} will react with a "thumbs up" emoji to acknowledge the command, and may respond with a comment on the pull request. While {% data variables.product.prodname_dependabot %} usually responds quickly, some commands may take several minutes to complete if {% data variables.product.prodname_dependabot %} is busy processing other updates or commands. -If you run any of the commands for ignoring dependencies or versions, {% data variables.product.prodname_dependabot %} stores the preferences for the repository centrally. While this is a quick solution, for repositories with more than one contributor it is better to explicitly define the dependencies and versions to ignore in the configuration file. This makes it easy for all contributors to see why a particular dependency isn't being updated automatically. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#ignore)." +If you run any of the commands for ignoring dependencies or versions, {% data variables.product.prodname_dependabot %} stores the preferences for the repository centrally. While this is a quick solution, for repositories with more than one contributor it is better to explicitly define the dependencies and versions to ignore in the configuration file. This makes it easy for all contributors to see why a particular dependency isn't being updated automatically. + +{% ifversion dependabot-version-updates-groups %}If you use the `groups` configuration option, you cannot use the `@dependabot ignore` comment on the pull request. You must instead define the dependencies to ignore in the configuration file.{% endif %} + +For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#ignore)." diff --git a/content/code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-errors.md b/content/code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-errors.md index 1a5a5f35a0..5b26c9c6fb 100644 --- a/content/code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-errors.md +++ b/content/code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-errors.md @@ -145,6 +145,46 @@ To allow {% data variables.product.prodname_dependabot %} to update the dependen **Version updates only.** {% data reusables.dependabot.private-dependencies-note %} Additionally, {% data variables.product.prodname_dependabot %} doesn't support private {% data variables.product.prodname_dotcom %} dependencies for all package managers. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems)." +{% ifversion dependabot-version-updates-groups %} + +### {% data variables.product.prodname_dependabot %} fails to group a set of dependencies into a single pull request + +{% data reusables.dependabot.dependabot-version-updates-groups-beta %} + +You must configure groups per package ecosystem. + +{% data reusables.dependabot.dependabot-version-updates-groups-supported %} + +For more information on how to configure groups for {% data variables.product.prodname_dependabot_version_updates %}, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups)." + +### {% data variables.product.prodname_dependabot %} fails to update one of the dependencies in a grouped pull request + +{% data reusables.dependabot.dependabot-version-updates-groups-beta %} + +**Version updates only.** {% data variables.product.prodname_dependabot %} will show the failed update in your logs, as well as in the job summary at the end of your logs. You should use the `@dependabot recreate` comment on the pull request to build the group again. For more information, see "[AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands)." + +If the dependency still fails to update, you should use the `exclude-patterns` configuration so that the dependency is excluded from the group. {% data variables.product.prodname_dependabot %} will then raise a separate pull request to update the dependency. + +If the dependency still fails to update, there may be a problem with the dependency itself, or with {% data variables.product.prodname_dependabot %} for that specific ecosystem. + +If you want to ignore version updates for the dependency, you must configure an `ignore` rule for the dependency in the `dependabot.yml` file. + +For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)." + +### Continuous integration (CI) fails on my grouped pull request + +{% data reusables.dependabot.dependabot-version-updates-groups-beta %} + +**Version updates only.** If the failure is due to a single dependency, you should use the `exclude-patterns` configuration so that the dependency is excluded from the group. {% data variables.product.prodname_dependabot %} will then raise a separate pull request to update the dependency. + +If you want to ignore version updates for the dependency, you must configure an `ignore` rule for the dependency in the `dependabot.yml` file. + +For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)." + +If you continue to see CI failures, you should remove the group configuration so that {% data variables.product.prodname_dependabot %} reverts to raising individual pull requests for each dependency. Then, you should check and confirm that the update works correctly for each individual pull request. + +{% endif %} + ## Triggering a {% data variables.product.prodname_dependabot %} pull request manually If you unblock {% data variables.product.prodname_dependabot %}, you can manually trigger a fresh attempt to create a pull request. diff --git a/data/features/dependabot-version-updates-groups.yml b/data/features/dependabot-version-updates-groups.yml new file mode 100644 index 0000000000..faf9a6f82c --- /dev/null +++ b/data/features/dependabot-version-updates-groups.yml @@ -0,0 +1,6 @@ +# Reference: Issue #10346 +# Dependabot Grouped Updates - [Public Beta] + +versions: + fpt: '*' + ghec: '*' diff --git a/data/reusables/dependabot/configuration-options.md b/data/reusables/dependabot/configuration-options.md index b8d9a2f21a..32abbc42cd 100644 --- a/data/reusables/dependabot/configuration-options.md +++ b/data/reusables/dependabot/configuration-options.md @@ -6,7 +6,8 @@ | [`allow`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow) | {% octicon "x" aria-label="Not supported" %}| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Customize which updates are allowed | | [`assignees`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#assignees) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Assignees to set on pull requests | | [`commit-message`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#commit-message) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Commit message preferences |{% ifversion fpt or ghec or ghes %} -| [`enable-beta-ecosystems`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#enable-beta-ecosystems) | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Enable ecosystems that have beta-level support |{% endif %} +| [`enable-beta-ecosystems`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#enable-beta-ecosystems) | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Enable ecosystems that have beta-level support |{% endif %}{% ifversion dependabot-version-updates-groups %} +| [`groups`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Group updates for certain dependencies |{% endif %} | [`ignore`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#ignore) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Ignore certain dependencies or versions | | [`insecure-external-code-execution`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#insecure-external-code-execution) | {% octicon "x" aria-label="Not supported" %}| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Allow or deny code execution in manifest files | | [`labels`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#labels) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Labels to set on pull requests | diff --git a/data/reusables/dependabot/dependabot-version-updates-groups-about.md b/data/reusables/dependabot/dependabot-version-updates-groups-about.md new file mode 100644 index 0000000000..7117d9f5f0 --- /dev/null +++ b/data/reusables/dependabot/dependabot-version-updates-groups-about.md @@ -0,0 +1 @@ +By default, {% data variables.product.prodname_dependabot %} raises a single pull request for each dependency that needs to be updated to a newer version. You can use `groups` to create sets of dependencies (per package manager), so that {% data variables.product.prodname_dependabot %} opens a single pull request to update multiple dependencies at the same time. \ No newline at end of file diff --git a/data/reusables/dependabot/dependabot-version-updates-groups-beta.md b/data/reusables/dependabot/dependabot-version-updates-groups-beta.md new file mode 100644 index 0000000000..6eb5c04dfa --- /dev/null +++ b/data/reusables/dependabot/dependabot-version-updates-groups-beta.md @@ -0,0 +1,9 @@ +{% ifversion dependabot-version-updates-groups %} + +{% note %} + +**Note:** {% data variables.product.prodname_dependabot %} grouped updates are currently in beta and is subject to change. + +{% endnote %} + +{% endif %} \ No newline at end of file diff --git a/data/reusables/dependabot/dependabot-version-updates-groups-supported.md b/data/reusables/dependabot/dependabot-version-updates-groups-supported.md new file mode 100644 index 0000000000..77175b2aa3 --- /dev/null +++ b/data/reusables/dependabot/dependabot-version-updates-groups-supported.md @@ -0,0 +1 @@ +You can only create groups for {% data variables.product.prodname_dependabot_version_updates %}. {% data variables.product.prodname_dependabot_security_updates %} do not support grouped updates. \ No newline at end of file diff --git a/data/reusables/dependabot/dependabot-version-updates-groups-yaml-example.md b/data/reusables/dependabot/dependabot-version-updates-groups-yaml-example.md new file mode 100644 index 0000000000..d7df6ac13b --- /dev/null +++ b/data/reusables/dependabot/dependabot-version-updates-groups-yaml-example.md @@ -0,0 +1,28 @@ +```yaml +# dependabot.yml file with customized bundler configuration + +version: 2 +updates: + # Keep bundler dependencies up to date + - package-ecosystem: "bundler" + directory: "/" + schedule: + interval: "weekly" + # Create a group of dependencies to be updated together in one pull request + groups: + # Specify a name for the group, which will be used in pull request titles + # and branch names + dev-dependencies: + # Define patterns to include dependencies in the group (based on + # dependency name) + patterns: + - "rubocop" # A single dependency name + - "rspec*" # A wildcard string that matches multiple dependency names + - "*" # A wildcard that matches all dependencies in the package + # ecosystem. Note: using "*" may open a large pull request + # Define patterns to exclude dependencies from the group (based on + # dependency name) + exclude-patterns: + - "gc_ruboconfig" + - "gocardless-*" +``` \ No newline at end of file diff --git a/data/reusables/dependabot/initial-updates.md b/data/reusables/dependabot/initial-updates.md index f43410b03c..6174215ad8 100644 --- a/data/reusables/dependabot/initial-updates.md +++ b/data/reusables/dependabot/initial-updates.md @@ -3,3 +3,5 @@ When you first enable version updates, you may have many dependencies that are o {% data variables.product.prodname_dependabot %} may also create pull requests when you change a manifest file after an update has failed. This is because changes to a manifest, such as removing the dependency that caused the update to fail, may cause the newly triggered update to succeed. To keep pull requests manageable and easy to review, {% data variables.product.prodname_dependabot %} raises a maximum of five pull requests to start bringing dependencies up to the latest version. If you merge some of these first pull requests before the next scheduled update, remaining pull requests will be opened on the next update, up to that maximum. You can change the maximum number of open pull requests by setting the [`open-pull-requests-limit` configuration option](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#open-pull-requests-limit). + +{% ifversion dependabot-version-updates-groups %}To further reduce the number of pull requests you may be seeing, you can use the [`groups`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) configuration option to group sets of dependencies together (per package ecosystem). {% data variables.product.prodname_dependabot %} then raises a single pull request to update as many dependencies as possible in the group to the latest versions at the same time.{% endif %}