# Automate Transformations Management with Rudder CLI and GitHub Actions


> Leverage GitHub Actions for automated validation, testing, and deployment of your RudderStack transformations.



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](https://github.com/rudderlabs/rudder-cli-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).
- A [workspace-level Service Access Token](https://www.rudderstack.com/docs/access-management/service-access-tokens/#workspace-sat) with the following [permissions](https://www.rudderstack.com/docs/access-management/policies-overview/#resource-permissions):

| Resource | Permissions |
| :----| :-----|
| Transformations | **Edit**, **Connect**, **Create & Delete** |
| Transformation Libraries | **Edit** |

- **If you're on Free or self-hosted plan, or for testing and development only**: Generate a [Personal Access Token](https://www.rudderstack.com/docs/access-management/personal-access-tokens/) with **Read-Write** role
**Warning:** Any action authenticated by a Personal Access Token will break if the user generating the token is removed from the organization or there is a breaking change to their permissions.

**Token permissions for legacy RBAC system**

If you are on the [legacy Permissions Management (RBAC) system](https://www.rudderstack.com/docs/archive/dashboard-guides/user-management/), your workspace-level Service Access Token should have the **Admin** role and **Grant edit access** toggled on under **Transformations**.

See [Generate a workspace-level Service Access Token](https://www.rudderstack.com/docs/archive/dashboard-guides/service-access-tokens/#generate-service-access-token) for steps to create the token.

![workspace-level Service Access Token with Transformations Admin permission](/docs/images/access-management/permissions/legacy/admin-transformations.webp)

## Setup

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

### Step 1: Configure repository secrets

1. In your GitHub repository, go to **Settings** > **Secrets and variables** > **Actions**.
2. Add a new repository secret:
   - **Name**: `RUDDERSTACK_ACCESS_TOKEN`
   - **Value**: The access token generated in the [Prerequisites](#prerequisites) section.

**Warning**

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`:

```yaml
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.