You are viewing documentation for an older version.

Click here to view the latest documentation.

Experimental feature

includes is an experimental feature that is disabled by default. You must explicitly opt in by enabling experimental mode and the eventRuleIncludes flag before you can use it. Experimental features are functional but can change or be removed in future releases, so avoid relying on them in production workflows.

This guide shows you how to share event rules between Tracking Plans using the experimental includes feature in Rudder CLI.

Overview

The includes directive lets a Tracking Plan inherit event rules from another Tracking Plan. This eliminates duplication when multiple plans share common rules.

When you apply your project, Rudder CLI:

1. Expands each includes reference
2. Pulls in the matching event_rule entries from the referenced Tracking Plan
3. Merges them into the current plan before pushing to RudderStack

The resulting Tracking Plan behaves exactly as if those rules had been defined inline.

Compatibility

If you use includes in a rudder/v1 (kind: tracking-plan) spec, Rudder CLI rejects validation with:

error[datacatalog/tracking-plans/spec-syntax-valid]: includes is not supported for tracking-plan v1 event rules

Prerequisites

Before using includes:

1. Install Rudder CLI and authenticate the tool.
2. Set up a Data Catalog project with Events and Properties defined in it.
3. Create at least one rudder/v0.1 Tracking Plan in the same project whose event rules you want to reuse.

Enable the experimental flag

Using includes requires two settings to be enabled:

1. Experimental mode (experimental): The master switch for all experimental features. While it is off, Rudder CLI ignores every experimental flag.
2. The eventRuleIncludes flag: Turns on includes specifically.

If either is disabled, Rudder CLI rejects any rule that uses includes during validation with the error 'includes' is not supported.

Enable both using any of the following methods.

{
  "experimental": true,
  "flags": {
    "eventRuleIncludes": true
  }
}

rudder-cli experimental enable eventRuleIncludes

rudder-cli experimental list

export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_EVENT_RULE_INCLUDES=true

All experimental settings default to false and require explicit opt-in. Experimental-flag environment variables take the form RUDDERSTACK_X_<FLAG_NAME>, where the flag name is converted to upper snake case (eventRuleIncludes → RUDDERSTACK_X_EVENT_RULE_INCLUDES).

Reference syntax

To include event rules from another Tracking Plan, add a rule with an includes block instead of an event block. The $ref value follows this pattern:

#/tp/<tracking-plan-id>/event_rule/<rule-id-or-*>

Where:

• <tracking-plan-id> is the id of the Tracking Plan whose event rules you want to reuse. It must exist in the same project (same Data Catalog directory) and must also use the rudder/v0.1 spec.
• <rule-id-or-*> is the id of a specific event rule, or * to include every event rule from the referenced plan.

Include all event rules

Use the * wildcard to inherit every event rule defined in another Tracking Plan. In the example below, the crm-plan plan includes all rules from common-rules-plan alongside its own rule:

# data-catalog/trackingplans/crm-plan.yaml
version: "rudder/v0.1"
kind: "tp"
metadata:
  name: "crm-plan"
spec:
  display_name: "CRM - Salesforce Plan"
  id: "crm-plan"
  rules:
    - includes:
        $ref: "#/tp/common-rules-plan/event_rule/*"
      id: "common-rules-include"
      type: "event_rule"
    - event:
        $ref: "#/events/crm-events/opportunity-converted"
        allow_unplanned: false
        identity_section: "properties"
      id: "opportunity-converted-rule"
      properties:
        - $ref: "#/properties/common-properties/project-code"
          required: true
      type: "event_rule"

After expansion, crm-plan contains every event rule from common-rules-plan, plus its own opportunity-converted-rule.

Include a specific event rule

To reuse only one rule, reference it by its id instead of using the wildcard:

rules:
  - includes:
      $ref: "#/tp/common-rules-plan/event_rule/identify-rule"
    id: "identify-include"
    type: "event_rule"
  - event:
      $ref: "#/events/crm-events/opportunity-converted"
    id: "opportunity-converted-rule"
    properties:
      - $ref: "#/properties/common-properties/project-code"
        required: true
    type: "event_rule"

This includes only the identify-rule from common-rules-plan.

Avoid including the same event into a plan more than once — whether directly or through an includes reference. Rudder CLI flags duplicate events introduced via includes during validation.

Constraints

• A rule can have either event or includes, not both. Specifying both fails validation with event and includes cannot be specified together; specifying neither fails with event or includes is required.
• An includes-only rule does not need an event field — the event is inherited from the referenced plan.
• The $ref value must match the pattern #/tp/<id>/event_rule/<id-or-*>, where IDs contain only alphanumeric characters, hyphens, and underscores. A malformed reference fails validation with '$ref' is not valid: must be of pattern #/tp/<group>/event_rule/<id-or-*>.

Validate and deploy

Validate and deploy plans that use includes exactly as you would any other Tracking Plan. Make sure experimental mode and the eventRuleIncludes flag are enabled in the same environment that runs these commands.

1. Validate your definitions:

rudder-cli validate -l ~/tutorial-catalog

2. Review the changes before deploying:

rudder-cli apply -l ~/tutorial-catalog --dry-run

3. Deploy the validated Tracking Plans:

rudder-cli apply -l ~/tutorial-catalog

Use includes in CI/CD

In CI/CD environments, enable experimental mode and the flag with environment variables instead of interactive commands.

jobs:
  apply:
    runs-on: ubuntu-latest
    env:
      RUDDERSTACK_CLI_EXPERIMENTAL: "true"
      RUDDERSTACK_X_EVENT_RULE_INCLUDES: "true"
      RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      # ... install Rudder CLI, then validate and apply

#!/usr/bin/env bash
set -euo pipefail

export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_EVENT_RULE_INCLUDES=true

rudder-cli validate -l .
rudder-cli apply -l .

Next steps

• Create a Tracking Plan
• Update a Tracking Plan