Config Management

Environment

All commands via ssh web drush. Config sync directory: config/sync/ (relative to project root).

Config export/import workflow

Standard workflow

# Export (after making changes in UI or code)
ssh web drush cex -y

# Import (when pulling changes from git)
ssh web drush cim -y

# Preview what will change on import
ssh web drush cim --diff

Verify after export/import (ALWAYS)

# After cex or cim, this should report "No differences":
ssh web drush config:status

Resolving import conflicts

# Check current config status
ssh web drush config:status

# "Only in sync dir" — new config to import
# "Only in DB" — needs export or was deleted intentionally
# "Different" — conflict to resolve

If cex/cim fails

| Error | Cause | Fix | |-------|-------|-----| | "Site UUID ... does not match" on cim | Sync dir from a different site | Only if intentional: ssh web drush config:set system.site uuid -y, then retry | | Unmet dependency / unknown module on cim | Config references a missing module | ssh web composer require drupal/ + ssh web drush en -y, then retry | | Validation/schema error on cim | Invalid config in sync dir | Read the named file in config/sync/, fix it (or re-export from a working env), retry | | cex writes nothing | No changes to export | Confirm with ssh web drush config:status — that is normal |

Config Split setup

Installation

ssh web composer require drupal/config_split
ssh web drush en config_split -y

Directory structure

config/
├── sync/          # Base config (shared across all environments)
├── splits/
│   ├── dev/       # Dev-only config (devel, kint, etc.)
│   ├── stage/     # Stage-specific overrides
│   └── prod/      # Production overrides

settings.php activation

// settings.local.php (dev)
$config['config_split.config_split.dev']['status'] = TRUE;
$config['config_split.config_split.stage']['status'] = FALSE;
$config['config_split.config_split.prod']['status'] = FALSE;

// settings.php (prod)
$config['config_split.config_split.dev']['status'] = FALSE;
$config['config_split.config_split.prod']['status'] = TRUE;

Common splits

| Split | Modules | Purpose | |-------|---------|---------| | dev | devel, kint, webprofiler, fieldui, viewsui | Development tools | | stage | stagefileproxy | Asset proxying | | prod | redis, cdn, advagg | Performance modules |

Config schema (REQUIRED for all config)

Every module with configuration MUST have config/schema/{module}.schema.yml.

Schema types reference

{module_name}.settings:
  type: config_object
  label: '{Module Name} settings'
  mapping:
    enabled:
      type: boolean
      label: 'Enabled'
    api_key:
      type: string
      label: 'API Key'
    max_items:
      type: integer
      label: 'Maximum items'
    allowed_types:
      type: sequence
      label: 'Allowed content types'
      sequence:
        type: string
        label: 'Content type'

Settings.php overrides

// Environment-specific overrides (not exported to config)
$config['system.performance']['css']['preprocess'] = TRUE;
$config['system.performance']['js']['preprocess'] = TRUE;
$config['system.logging']['error_level'] = 'hide';

// Sensitive values (never in config/sync/)
$settings['hash_salt'] = getenv('HASH_SALT');
$config['smtp.settings']['smtp_password'] = getenv('SMTP_PASSWORD');

Verification

# Check config sync status
ssh web drush config:status

# Validate config schema (check for missing schemas)
ssh web drush config:inspect

# Verify config split is active
ssh web drush config:get config_split.config_split.dev status

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trebormc
• Source: trebormc/drupal-ai-agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.