rules

Configuration

name: rules

type: array

default: []

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "rules": []
    }
  }
}

Define package-specific configuration rules that override the default settings.

This option is currently in beta. This means its options are considered stable (no backwards incompatible changes will be added), but that there are some stability and usability improvements expected.

Explanation

The rules option allows you to apply different configuration settings to different groups of packages. This is useful when you want to handle certain packages differently from your default configuration. For example, you might want to apply security-only updates to development tools while allowing all updates for production dependencies.

Rules are evaluated in order, and when a package matches a rule, the configuration from that rule is merged with your default configuration.

Comparison with bundled_packages

If you want to group packages together in a more flexible pattern than using bundled_packages, then rules is for you. The main differences are:

• bundled_packages will only update its bundled packages if the "parent" package has an update, while rules can update the group if any of the packages has an update.
• Rules make it possible to have different configurations per group. For example, you can automerge one group but not others.
• Rules support pattern matching with wildcards and negation, making them much more flexible.

Grouping into a single pull request

When a rule matches more than one package, those packages are collected into a single grouped pull request instead of getting one pull request each. The pull request is titled Update group `<name>` (using the rule's name), and it is created whenever any of the matched packages has an update available.

This grouping is driven entirely by the rule's matchRules — the packages that match are the packages that get grouped. It applies to every rule, even one whose only purpose is to override configuration. For example, the Custom branch prefixes per package group rules below will each produce one combined pull request for their matched packages, not a separate pull request per package.

Structure

Rules is an array of rule objects. Each rule object has the following structure:

{
  "rules": [
    {
      "name": "Human readable name",
      "slug": "machine-readable-slug",
      "matchRules": [
        {
          "type": "names",
          "values": ["vendor/*", "!vendor/excluded-package"]
        }
      ],
      "config": {
        "blocklist": [],
        "branch_prefix": "deps/",
        "security_updates_only": 1
      }
    }
  ]
}

Rule Properties

Property	Type	Description
name	string	A human-readable name for the rule. Used as the title and body heading of the grouped pull request (Update group `<name>`)
slug	string	A machine-readable identifier for the rule. Used to build the git branch name for the grouped pull request. If omitted, the branch name is derived from a slugified name
matchRules	array	An array of match rule objects that determine which packages this rule applies to
config	object	Configuration options to apply when a package matches

Match Rules

Match rules determine which packages a rule applies to. Each match rule has a type and associated properties.

Note: You can list more than one match rule object in the matchRules array. When you do, all of them must match for the rule to apply — the match rule objects are combined with a logical AND. (Within a single names match rule, the values are combined with OR, and a negative ! pattern excludes a package regardless of the positive patterns.)

Type: names

Match packages by name using fnmatch patterns.

Pattern	Description
vendor/*	Match all packages from a vendor
vendor/package	Match a specific package
vendor/prefix-*	Match packages with a specific prefix
!vendor/package	Exclude a specific package (negative match)

When using negative matches (!), the package is excluded from the rule even if it matches a positive pattern. This allows you to select a broad group of packages and then exclude specific ones.

{
  "matchRules": [
    {
      "type": "names",
      "values": [
        "drupal/*",
        "!drupal/core-recommended",
        "!drupal/core-composer-scaffold"
      ]
    }
  ]
}

This example matches all drupal/* packages except drupal/core-recommended and drupal/core-composer-scaffold.

Config Overrides

Within a rule's config object, you can override most configuration options. The configuration from matching rules is merged with your default configuration.

Note: Merging is done per option, with the last writer winning — a value set in a rule replaces the corresponding value entirely rather than being combined with it. For example, a rule that sets labels or blocklist replaces the root value for matched packages; it does not append to it.

Overridable Options

The following options can be used within rules:

• allow_update_indirect_with_direct
• allow_updates_beyond_constraint
• assignees
• automerge
• automerge_method
• automerge_method_security
• automerge_security
• blocklist
• branch_prefix
• bundled_packages
• commit_message_convention
• default_branch
• default_branch_security
• labels
• labels_security
• one_pull_request_per_package
• run_scripts
• security_updates_only
• update_with_dependencies

Root-level Only Options

The following options cannot be overridden in rules and only apply at the root configuration level. These options control global filtering that happens before rules are evaluated:

• allow_list
• allow_security_updates_on_concurrent_limit
• always_allow_direct_dependencies
• always_update_all
• check_only_direct_dependencies
• composer_outdated_flag
• extends
• ignore_platform_requirements
• number_of_concurrent_updates
• timeframe_disallowed
• timezone
• update_dev_dependencies

Examples

Security-only updates for dev dependencies

Only receive security updates for development tools while allowing all updates for production dependencies:

Note: Because this rule matches more than one package, all matched dev-tool updates are grouped into a single pull request titled Update group `Dev tools - security only` rather than one pull request per package.

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "rules": [
        {
          "name": "Dev tools - security only",
          "slug": "dev-tools-security",
          "matchRules": [
            {
              "type": "names",
              "values": ["phpunit/*", "phpstan/*", "squizlabs/*", "friendsofphp/*"]
            }
          ],
          "config": {
            "security_updates_only": 1
          }
        }
      ]
    }
  }
}

Bundling Drupal Core packages

Bundle all Drupal core packages together so they update in a single pull request:

{
  "name": "company/drupal-project",
  "extra": {
    "violinist": {
      "rules": [
        {
          "name": "Drupal Core packages",
          "slug": "drupal-core",
          "matchRules": [
            {
              "type": "names",
              "values": ["drupal/core-recommended"]
            }
          ],
          "config": {
            "bundled_packages": {
              "drupal/core-recommended": [
                "drupal/core-composer-scaffold",
                "drupal/core-project-message"
              ]
            }
          }
        }
      ],
      "blocklist": [
        "drupal/core-composer-scaffold",
        "drupal/core-project-message"
      ]
    }
  }
}

Note: This example works because the rule matches a single package (drupal/core-recommended), which keeps it off the grouping path — a bundled_packages value set inside a rule's config is only honored for individual (non-grouped) updates. If you broaden matchRules so the rule matches more than one package, those packages are grouped automatically and the rule's bundled_packages is ignored. In that case, bundle additional packages by adding them to the rule's matchRules instead, or set bundled_packages at the root level.

Custom branch prefixes per package group

Use different branch prefixes for different types of dependencies:

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "rules": [
        {
          "name": "Framework updates",
          "slug": "framework",
          "matchRules": [
            {
              "type": "names",
              "values": ["symfony/*", "laravel/*"]
            }
          ],
          "config": {
            "branch_prefix": "deps/framework/"
          }
        },
        {
          "name": "Testing tools",
          "slug": "testing",
          "matchRules": [
            {
              "type": "names",
              "values": ["phpunit/*", "mockery/*", "fakerphp/*"]
            }
          ],
          "config": {
            "branch_prefix": "deps/testing/"
          }
        }
      ]
    }
  }
}

Automerge updates for trusted packages

Automatically merge updates for a set of well-tested packages while requiring manual review for everything else:

{
  "name": "company/project",
  "extra": {
    "violinist": {
      "rules": [
        {
          "name": "Trusted packages - automerge",
          "slug": "trusted-automerge",
          "matchRules": [
            {
              "type": "names",
              "values": ["psr/*", "symfony/polyfill-*"]
            }
          ],
          "config": {
            "automerge": 1,
            "automerge_method": "rebase"
          }
        }
      ]
    }
  }
}

Rule Precedence

When a package matches multiple rules, the configurations are merged in order. Later rules can override settings from earlier rules. If you have overlapping patterns, place more specific rules after more general ones.

Note: Root-level configuration is always applied first, then rules are evaluated and merged in the order they appear.