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


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]({{< ref "access-management/service-access-tokens.md#workspace-sat" >}}) with the following permissions:

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

{{< customreadfile "/includes/rudder-cli/token-auth-footer-transformations.md" >}}

## 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 `<VERSION>` 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.
{{< /info >}}

## 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 /> <span style="color: #4D4DFF;font-size:12px;">Required</span> |  Path to the folder containing Rudder CLI project files | - |
| `access_token` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> |  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 /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Path to the folder containing Rudder CLI project files | - |
| `access_token` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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 /> <span style="color: #4D4DFF;font-size:12px;">Required</span>   |  Path to the folder containing Rudder CLI project files. | -             |
| `access_token` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | 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.