Migrate only permissions that exist on the destination

A new migrate destination plugin handles entity:user_role. This plugin will only migrate permissions that exist on both the source and destination site.

Before Drupal 10.0.0

All permissions from the source were migrated, even if they did not exist on the destination. When the permission was not provided by a module on the destination site, the permissions would be included in configuration export but not visible from the UI. This made it difficult to remove any unwanted permissions.

If a module is added later that provides these permissions, then some roles might unexpectedly have permissions from that module.

Starting with Drupal 10.0.0

A message is logged for each user role that has permissions removed. Site owners should check the logs after any migration that creates or updates user roles to see what permissions have been removed.

Some permissions depend on configuration. For example, the Node module provides the permission "Article: Edit any content" if there is an Article content type. The role migrations in Drupal core now include optional dependencies so that the role migrations will be executed after migrations that create such configuration. This will minimize the number of valid permissions that are removed when migrating using only Drupal core.

Before

Here is part of the d7_user_role migration:

id: d7_user_role
label: User roles
source:
  plugin: d7_user_role
...
destination:
  plugin: entity:user_role
migration_dependencies:
  optional:
    - d7_filter_format

All permissions are migrated even if there is no module providing that permission on the destination.

After

id: d7_user_role
label: User roles
source:
  plugin: d7_user_role
...
destination:
  plugin: entity:user_role
migration_dependencies:
  optional:
    - block_content_type
    - contact_category
    - d7_comment_type
    - d7_filter_format
    - d7_node_type
    - d7_shortcut_set
    - d7_taxonomy_vocabulary
    - d7_taxonomy_vocabulary_translation

Permissions are migrated only if there is a module that provides them. When executing migrations through the UI, the optional dependencies will create configuration before the role migration is executed.

You can see what permissions have been removed

• by querying the database table, such as migrate_message_d7_user_role;
• with Drush: for example drush migrate:message d7_user_role;
• by reviewing the logs, /admin/reports/dblog?type[migrate_drupal_ui]=migrate_drupal_ui, only if the migration was run from /upgrade.
• in the admin UI, after #3063856: Add ability to view migrate_message table data.

Ensure that all modules that provide permissions are enabled on the destination site before running an upgrade, /upgrade. For example, if the source site has the backup_migrate module enabled, then enable it on the destination site before the migration.

If your custom migrations have the effect of creating permissions, then add those migrations as dependencies to d6_user_role.yml or d7_user_role.yml. Refer to those migrations in core/modules/user/migrations/ for all the core migrations that affect permissions. You can implement hook_migration_plugins_alter() in
order to add dependencies to the core migrations:

    function mymodule_migration_plugins_alter(array &$migrations) {
      foreach (['d6_user_role', 'd7_user_role'] as $core_role_migration) {
        if (isset($migrations[$core_role_migration])) {
          $migrations[$core_role_migration]['migration_dependencies']['optional'][] = 'mymodule_custom_migration';
        }
      }
    }