Add isort dependabot auto-migration workflow (#585)

This migration works like `black` migration, it runs `isort` on all
files when Dependabot bumps `isort`, so any import-ordering changes
introduced by the upgrade are applied automatically to the PR.

Author: llucax

.github/dependabot.yml

@@ -29,6 +29,7 @@ updates:
         exclude-patterns:
           # pydoclint has shipped breaking changes in patch updates often
           - "pydoclint"
+          - "isort"
       minor:
         update-types:
           - "minor"
@@ -41,6 +42,7 @@ updates:
           - "mkdocstrings[python]"
           - "pydoclint"
           - "pytest-asyncio"
+          - "isort"
       mkdocstrings:
         patterns:
           - "mkdocstrings*"

.github/workflows/auto-dependabot.yaml

@@ -22,7 +22,8 @@ jobs:
     name: Auto-merge Dependabot PR
     if: |
       github.actor == 'dependabot[bot]' &&
-      !contains(github.event.pull_request.title, 'Bump black from ')
+      !contains(github.event.pull_request.title, 'Bump black from ') &&
+      !contains(github.event.pull_request.title, 'Bump isort from ')
     runs-on: ubuntu-slim
     steps:
       - name: Generate GitHub App token

.github/workflows/isort-migration.yaml

@@ -0,0 +1,92 @@
+# Automatic isort migration for Dependabot PRs
+#
+# When Dependabot upgrades isort, this workflow installs the new version and
+# runs `isort .` so the PR already contains any import-ordering changes
+# introduced by the upgrade, while leaving the PR open for review.
+#
+# isort follows SemVer but its release policy
+# (https://github.com/PyCQA/isort/blob/main/docs/major_releases/release_policy.md)
+# explicitly allows intentional formatting changes in minor releases, and
+# patch releases may also adjust output in smaller bug-fix ways.  Because of
+# that, isort is excluded from the regular `patch` and `minor` Dependabot
+# groups: every isort bump produces an individual `Bump isort from …` PR and
+# is routed through this migration workflow.
+#
+# The companion auto-dependabot workflow skips those PRs so they're handled
+# exclusively by this migration workflow.
+#
+# XXX: !!! SECURITY WARNING !!!
+# pull_request_target has write access to the repo, and can read secrets.
+# This is required because Dependabot PRs are treated as fork PRs: the
+# GITHUB_TOKEN is read-only and secrets are unavailable with a plain
+# pull_request trigger.  The action mitigates the risk by:
+#   - Never executing code from the PR (the migration script is embedded
+#     in this workflow file on the base branch, not taken from the PR).
+#   - Gating migration steps on github.actor == 'dependabot[bot]'.
+#   - Running checkout with persist-credentials: false and isolating
+#     push credentials from the migration script environment.
+# For more details read:
+# https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+
+name: isort Migration
+
+on:
+  merge_group:  # To allow using this as a required check for merging
+  pull_request_target:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  # Commit reformatted files back to the PR branch.
+  contents: write
+  # Create and normalize migration state labels.
+  issues: write
+  # Read/update pull request metadata and comments.
+  pull-requests: write
+
+jobs:
+  isort-migration:
+    name: Migrate isort
+    # Skip if it was triggered by the merge queue. We only need the workflow to
+    # be executed to meet the "Required check" condition for merging, but we
+    # don't need to actually run the job, having the job present as Skipped is
+    # enough.
+    if: |
+      github.event_name == 'pull_request_target' &&
+      github.actor == 'dependabot[bot]' &&
+      contains(github.event.pull_request.title, 'Bump isort from ')
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Generate token
+        id: create-app-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.FREQUENZ_AUTO_DEPENDABOT_APP_ID }}
+          private-key: ${{ secrets.FREQUENZ_AUTO_DEPENDABOT_APP_PRIVATE_KEY }}
+          # Push reformatted files to the PR branch.
+          permission-contents: write
+          # Create and normalize migration state labels.
+          permission-issues: write
+          # Read/update pull request metadata and labels.
+          permission-pull-requests: write
+      - name: Migrate
+        uses: frequenz-floss/gh-action-dependabot-migrate@27763fb5eb56476d91abe00132e8a0614171f92f # v1.2.0
+        with:
+          migration-script: |
+            import os
+            import subprocess
+            import sys
+
+            version = os.environ["MIGRATION_VERSION"].lstrip("v")
+            subprocess.run(
+                [sys.executable, "-Im", "pip", "install", f"isort=={version}"],
+                check=True,
+            )
+            subprocess.run([sys.executable, "-Im", "isort", "."], check=True)
+          token: ${{ steps.create-app-token.outputs.token }}
+          auto-merge-on-changes: "false"
+          version-iteration: "false"
+          sign-commits: "true"
+          auto-merged-label: "tool:auto-merged"
+          migrated-label: "tool:isort:migration:executed"
+          intervention-pending-label: "tool:isort:migration:intervention-pending"
+          intervention-done-label: "tool:isort:migration:intervention-done"

RELEASE_NOTES.md

@@ -32,6 +32,7 @@ But you might still need to adapt your code:
 - API projects now have a better grpcio/protobuf updates grouping in Dependabot, which should make upgrading easier, and plays nicer with the new `grpc-migration.yaml` workflow.
 - API projects should now use the new API-specific *Protect version branches* ruleset variant, which includes the required `Fix gRPC/protobuf runtime floors` check without affecting non-API Python projects.
 - Workflows using the `gh-action-dependabot-migrate` are upgraded to the latest version, which avoids unnecessary version iterations.
+- Add an `isort-migration.yaml` workflow that automatically reorders imports when Dependabot upgrades `isort`.
 
 ## Bug Fixes
 
@@ -44,6 +45,7 @@ But you might still need to adapt your code:
 - The issue template chooser (`config.yml`) no longer includes the `contact_links` section for private repositories, since GitHub Discussions are typically disabled for them.
 - Normalized the GitHub Action hashes for `gh-action-setup-git` and `gh-action-setup-python-with-deps` to point to the actual commit object, which is what Dependabot expects.
 - API projects now configure black with `extend-exclude = '^/submodules/'` so the formatting check doesn't descend into external git submodules that don't follow our formatting rules.
+- API projects now configure isort with `skip_glob = ["submodules/*"]` so the import-sorting check doesn't descend into external git submodules that don't follow our rules.
 - `CONTRIBUTING.md`
   * Fixed the nox example commands in  to use the correct `tests/` directory instead of the non-existent `test/` directory.
   * Fixed the wrong mention to PyPI publishing when releasing for private repositories.