# Automate Transformations Management with Rudder CLI and GitLab CI/CD


> Leverage GitLab CI/CD components for automating validation, testing, and deployment of your RudderStack transformations.



This guide explains how to validate, test, and manage your RudderStack transformations directly via GitLab CI/CD pipelines using the Rudder CLI CI/CD components.

## Overview

By leveraging the [Rudder CLI GitLab CI/CD components](https://gitlab.com/rudderstack/components/rudder-cli), you can:

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

## Prerequisites

- A GitLab 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:

| 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 GitLab CI/CD pipeline for your transformations.

### Step 1: Configure CI/CD variables

1. In your GitLab project, go to **Settings** > **CI/CD** > **Variables**.
2. Add a new variable:

   - **Key**: `RUDDERSTACK_ACCESS_TOKEN`
   - **Value**: The access token generated in the [Prerequisites](#prerequisites) section.
   - **Type**: Variable
   - **Protect variable**: Recommended for production branches
   - **Mask variable**: Recommended to hide the token in logs

### Step 2: Create GitLab CI/CD configuration

Create or update your `.gitlab-ci.yml` file in the root of your repository:

```yaml
stages: [validate, test, deploy]

include:
  # Validate transformation configurations
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/validate@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN

  # Test modified transformations in merge requests
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/transformations-test@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN
      applies_to: "modified"
      verbose: true
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"

  # Apply changes when merged to the default branch
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/apply@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN
    rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

**Info**

Replace `&lt;VERSION&gt;` with the latest version of the Rudder CLI component. 

See the [Rudder CLI GitLab component releases](https://gitlab.com/rudderstack/components/rudder-cli/-/releases) for the latest version.

## Components

The following Rudder CLI CI/CD components are available for managing transformations:

### `validate`

This component validates the project structure and YAML configurations in the specified directory. By default, jobs defined in this component run in the `validate` stage.

#### Example

```yaml
include:
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/validate@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN
```

#### Inputs

| Input | Description | Default value |
| :------------- | :------- | :---------- | 
| `location`  <br /> Required |  Path to the folder containing Rudder CLI project files | - |
| `access_token` <br /> Required |  RudderStack access token  | - |
| `cli_version`  | Version of the Rudder CLI tool to use | `0.13.1` |
| `stage` | Stage in which the job should run | `validate`    |

### `transformations-test`

This component tests transformations defined in your project by executing their code against test input events. By default, jobs defined in this component run in the `test` stage.

#### Example

```yaml
include:
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/transformations-test@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN
      applies_to: "modified"
```

#### Inputs

| Input          | Description | Default value |
| :------------- | :------- | :---------- | 
| `location` <br /> Required | Path to the folder containing Rudder CLI project files | - |
| `access_token` <br /> Required | RudderStack access token | - |
| `applies_to` | Test mode: `all` or `modified` | `modified`    |
| `verbose` | Show detailed output including diffs for failures | `false`       |
| `cli_version`  | Version of the Rudder CLI tool to use | `0.13.1` |
| `stage` | Stage in which the job should run | `test` |

### `apply`

This component syncs the transformation and library definitions in the specified directory to your RudderStack workspace. By default, jobs defined in this component run in the `deploy` stage.

#### Example

```yaml
include:
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/apply@<VERSION>
    inputs:
      location: "project/"
      access_token: $RUDDERSTACK_ACCESS_TOKEN
```

#### Inputs

| Input |  Description | Default value |
| :------------- | :------- | :---------- | 
| `location`  <br /> Required   |  Path to the folder containing Rudder CLI project files. | -             |
| `access_token` <br /> Required | RudderStack access token | - |
| `dry_run` | Enable dry-run mode to see changes without applying. | `false` |
| `cli_version`  | Version of the Rudder CLI tool to use. | `0.13.1` |
| `stage` | Stage in which the job should run. | `deploy` |

### `transformations-show-default-events`

This component displays the default test events used when no test files are configured for transformations.

#### Example

```yaml
include:
  - component: $CI_SERVER_FQDN/rudderstack/components/rudder-cli/transformations-show-default-events@<VERSION>
```

#### Inputs

| Input | Description | Default value |
| :------------ | :------- | :---------- |
| `cli_version` | Version of the Rudder CLI tool to use. | `0.13.1` |
| `stage` | Stage in which the job should run. | `test` |

## How it works

- **Validation**: The `validate` component ensures your project files are correctly structured before any further steps.
- **Testing**: The `transformations-test` component runs your transformation code against defined test cases. Using `applies_to: modified` in merge requests is recommended for faster feedback.
- **Deployment**: When changes are merged into the default branch, the `apply` component pushes the updates to your RudderStack workspace.