Config Ignore
A module that allows specific Drupal configurations to be ignored during configuration import and export operations.
config_ignore
Install
composer require 'drupal/config_ignore:8.x-3.3'
Overview
Config Ignore provides a powerful mechanism to prevent certain configuration items from being overwritten during configuration synchronization operations. This is particularly useful in scenarios where site-specific settings like site name, email addresses, or development module configurations should remain unchanged across different environments.
The module integrates with Drupal's configuration management system through event subscribers, intercepting storage transform events to filter out ignored configurations. It supports three operational modes (Simple, Intermediate, and Advanced) to cater to different complexity needs, from basic ignore lists to granular control over import/export and create/update/delete operations.
Config Ignore supports wildcard patterns for matching multiple configurations, specific configuration key targeting for partial ignores, force import syntax using the tilde (~) prefix, and language collection filtering for multilingual sites.
Features
- Ignore entire configuration objects or specific keys within configurations during import/export
- Three operational modes: Simple (same rules for all operations), Intermediate (separate rules for import vs export), and Advanced (granular control over create/update/delete for both import and export)
- Wildcard pattern matching using asterisk (*) to match multiple configuration names (e.g., 'webform.webform.*' ignores all webforms)
- Force import syntax with tilde prefix (~) to explicitly allow importing configurations that would otherwise be matched by wildcards
- Partial configuration ignoring using colon syntax to ignore only specific keys (e.g., 'system.site:name' ignores only the site name)
- Language collection support for ignoring translated configuration (e.g., 'language.fr|system.site:name')
- Settings.php overrides for deactivation and event subscriber priority configuration
- Two alter hooks for programmatic modification of ignored configurations
- Cache tag invalidation for immediate configuration changes
Use Cases
Preserving site-specific settings across environments
When deploying configuration from development to production, site-specific settings like site name, email address, and slogan often need to remain different. Add 'system.site' to the ignore list to prevent these values from being overwritten during config import. This allows the production site to maintain its branding while still receiving other configuration updates.
Ignoring development module configurations
Development modules like Devel have settings that should not be transferred to production. Use wildcard patterns like 'devel.*' to ignore all Devel-related configurations. This prevents development settings from accidentally being deployed to production environments.
Partial configuration ignoring for email templates
When email templates need to vary by environment (e.g., different sender addresses), use key-specific patterns like 'user.mail:register_no_approval_required.body' to ignore only the email body while allowing other user mail settings to sync normally.
Ignoring all webforms except specific ones
Use the combination of wildcard and force import patterns: 'webform.webform.*' to ignore all webforms, then '~webform.webform.contact' to force import the contact form specifically. This is useful when most webforms are site-specific but certain ones should be managed in code.
Managing translation-specific configurations
For multilingual sites where translations should not be overwritten, use language collection patterns like 'language.fr|*' to ignore all French translations, or 'language.*|system.site:name' to ignore site name translations in all languages while allowing other translations to sync.
Preventing accidental content type deletion
In advanced mode, configure the delete operation to ignore 'node.type.*' on import. This prevents content types from being deleted if they exist on the site but were removed from the sync directory, providing a safety net against accidental content type removal.
Environment-specific API keys and credentials
Settings containing API keys or credentials that differ per environment can be ignored using patterns like 'mymodule.settings:api_key'. This ensures sensitive or environment-specific values are not overwritten during deployment.
Tips
- Start with Simple mode and only switch to Intermediate or Advanced mode if you have specific use cases requiring separate import/export rules or create/update/delete granularity
- Always test configuration ignore patterns in a development environment before deploying to production
- Use the force import prefix (~) carefully - it overrides wildcard matches and can lead to unexpected imports if not properly ordered
- Configuration ignore patterns are processed in order, with exclusion patterns (~) taking precedence when they match
- When debugging, check the config_ignore.settings configuration directly to verify patterns are saved correctly
- Consider using hook_config_ignore_ignored_alter for dynamic ignore rules that depend on site state or environment
- The module works with both drush config:import/export and the UI-based configuration synchronization
Technical Details
Admin Pages 1
/admin/config/development/configuration/ignore
Configure which configurations should be ignored during import and export operations. This page allows administrators to specify configuration patterns that should be excluded from the normal configuration synchronization process.
Permissions 1
Hooks 2
hook_config_ignore_settings_alter
Allows modules to programmatically add configuration patterns to the ignore list. This hook is deprecated in favor of hook_config_ignore_ignored_alter.
hook_config_ignore_ignored_alter
Allows modules to alter the ConfigIgnoreConfig object with full control over all ignore lists. Provides access to modify patterns for specific directions (import/export) and operations (create/update/delete).
Troubleshooting 6
Verify the pattern syntax is correct. Wildcards use * not %. Ensure there are no extra spaces. Check if force import (~) patterns are accidentally overriding your ignore rules. Also verify you're using the correct mode and that patterns are in the right field for your operation.
Never ignore 'core.extension' configuration as it controls enabled modules. Use the Config Split module instead for environment-specific modules.
Check if Config Ignore is deactivated via settings.php ($settings['config_ignore_deactivate'] = TRUE). Also verify the module is enabled and cache has been cleared.
Use the Single Import feature at /admin/config/development/configuration/single/import to import individual configurations without Config Ignore rules applying.
Adjust the priority via settings.php: $settings['config_ignore_import_priority'] = -100; and $settings['config_ignore_export_priority'] = 100; Higher priority means ignoring happens earlier.
Use the language collection syntax with pipe separator: 'language.LANGCODE|config.name' (e.g., 'language.fr|system.site' for French translations of system.site).
Security Notes 4
- Do not use Config Ignore to manage security-sensitive configurations that should be consistent across all environments
- Be cautious when ignoring permission-related configurations as this could lead to security inconsistencies between environments
- Ignoring user.role.* configurations could prevent important permission updates from being deployed
- Always review ignored configurations during security audits to ensure critical security updates are not being blocked