Dev-Tools: Automate Transformations Management with Rudder CLI and GitHub Actions

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to validate, test, and manage your RudderStack transformations directly via GitHub workflows using the Rudder CLI Project Manager Action.

Key features

By leveraging the Rudder CLI Project Manager Action, you can:

Validate: Check your transformation YAML configurations for syntax and structure.
Test: Execute transformation code against test events using the specialized transformations-test action.
Apply: Deploy your transformations and libraries to your RudderStack workspace automatically.

Prerequisites

A GitHub repository containing your Rudder CLI project files (transformations and libraries).

Generate a workspace-level Service Access Token in the RudderStack dashboard with the following permissions to manage Data Catalog and Tracking Plans:

Resource	Permissions
Tracking Plans	Create & Delete, Edit
Data Catalog	Edit

For testing or development purposes only: Generate a Personal Access Token with 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.

Token permissions for legacy RBAC system

If you are on the legacy Permissions Management (RBAC) system, your workspace-level Service Access Token should have Admin permissions.

See this documentation for more information on generating the token.

Setup

Follow these steps to set up the GitHub Actions workflow for your transformations.

Step 1: Configure repository secrets

In your GitHub repository, go to Settings > Secrets and variables > Actions.
Add a new repository secret:
- Name: RUDDERSTACK_ACCESS_TOKEN
- Value: The Service Access Token generated in the Prerequisites section.

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

Do not expose the token directly in your workflow files.

Step 2: Create Actions workflow

Create the following workflow in .github/workflows/ within your repository, for example, .github/workflows/transformations.yml:

name: Manage Transformations

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]
 paths:
 - "project/transformations/**"

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

 - name: Validate Project Files
 uses: rudderlabs/rudder-cli-action@v1.0.1
 env:
 RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
 with:
 location: "project/"
 mode: "validate"

 - name: Test Modified Transformations
 uses: rudderlabs/rudder-cli-action/transformations-test@v1.0.1
 env:
 RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
 with:
 location: "project/"
 scope: "modified"
 verbose: "true"

 apply:
 runs-on: ubuntu-latest
 needs: validate-and-test
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - name: Apply Changes
 uses: rudderlabs/rudder-cli-action@v1.0.1
 env:
 RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
 with:
 location: "project/"
 mode: "apply"

Action inputs

Main action (`rudderlabs/rudder-cli-action`)

Used for validate, dry-run, and apply modes.

Input	Description	Default
`location`	Path to the folder containing Rudder CLI project files.	-
`mode`	Operation mode: `validate`, `dry-run`, or `apply`.	-
`cli_version`	Version of the Rudder CLI tool to use.	`v0.13.1`

Test action (`rudderlabs/rudder-cli-action/transformations-test`)

Specialized action for running transformation tests.

Input	Description	Default
`location`	Path to the folder containing Rudder CLI project files.	-
`scope`	Test scope: `all` (all transformations) or `modified` (only changed ones).	-
`verbose`	Show detailed test output with diffs for failures.	`false`
`cli_version`	Version of the Rudder CLI tool to use.	`v0.13.1`

How it works

Validation: The validate mode ensures your YAML files are correctly formatted before any further steps.
Testing: The transformations-test action runs your transformation code against the defined test cases. Using scope: modified in PRs is recommended for faster feedback.
Deployment: When changes are merged into the main branch, the apply mode pushes the updates to your RudderStack workspace.

RudderStack Docs – Automate Project Management with Rudder CLI and GitHub Actions