Automate Tracking Plan Management with Rudder CLI and GitHub Actions Alpha

This guide explains how to automate tracking plan management using GitHub Actions and Rudder CLI.

Prerequisites

• A GitHub repository containing your tracking plan YAML files.
• In your RudderStack workspace, create a workspace-level Service Access Token or Personal Access Token (for testing purposes only) with minimum read-write role.

RudderStack recommends using a workspace-level Service Access Token for authentication.

Any action authenticated by a Personal Access Token will break if the user is removed from the organization or a breaking change is made to their permissions.

• Tracking plans organized in a dedicated directory, for example, tracking-plans/.

Setup

Follow the steps in the below sections in the exact order to create the GitHub Actions workflow.

Step 1: Configure repository secrets

1. In your GitHub repository, go to Settings > Secrets and variables > Actions.
2. Add a new repository secret as follows:

• Name: RUDDERSTACK_ACCESS_TOKEN
• Value: The RudderStack service access token generated in the Prerequisites section.

RudderStack recommends storing this token in GitHub Secrets and referencing it in your workflow using ${{ secrets.YOUR_SECRET_NAME }}.

Do not expose the token directly in your workflow files.

Step 2: Create GitHub Actions workflows

Create two workflow files in your .github/workflows/ directory:

• Main branch sync (tracking-plan-sync.yml)

name: Sync Tracking Plans

on:
  push:
    branches:
      - main
    paths:
      - "tracking-plans/**"

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync Tracking Plans
        uses: rudderlabs/rudder-tracking-plan-action@v1.0.0
        env:
          RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
        with:
          location: tracking-plans # Required
          mode: apply # Required

• Feature branch validation (tracking-plan-validate.yml)

name: Validate Tracking Plans

on:
  pull_request:
    paths:
      - "tracking-plans/**"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Tracking Plans
        uses: rudderlabs/rudder-tracking-plan-action@v1.0.0
        env:
          RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
        with:
          location: tracking-plans # Required
          mode: dry-run # Required

Some of the key inputs are described below:

Modes

The mode parameter defines the operation mode of the GitHub Action. You can specify either of the following values:

How it works

This section explains the GitHub Actions workflow.

Main branch (main)

• The action only triggers when files in the tracking-plans/ directory are modified.
• When you merge the changes to main, the action automatically syncs tracking plans with RudderStack.
• The action uses the apply mode (mode: apply) to push changes to RudderStack.

Feature branches

• The action runs in dry mode (mode: dry-run) when you create or update a pull request for safe validation.
• It shows which changes would be applied without actually applying them.
• The PR authors can review the impact of their changes.

Questions? Contact us by email or on Slack