# Automate Project Management with Rudder CLI and GitHub Actions


This guide explains how to validate and manage your Rudder CLI projects directly via GitHub workflows.

## Key features

By leveraging the [Rudder CLI Project Manager Action](https://github.com/rudderlabs/rudder-cli-action), you can:

- Validate your Rudder CLI project files
- Perform a dry run of any changes to your project files
- Apply the changes to your RudderStack workspace

## Prerequisites

- A GitHub repository containing your Tracking Plan YAML files

- Generate a [workspace-level Service Access Token]({{< ref "access-management/service-access-tokens.md#workspace-sat" >}}) in the RudderStack dashboard with the following [permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to manage Data Catalog and Tracking Plans:

{{< customreadfile "/includes/rudder-cli/data-catalog-sat-token-options.md" >}}

## Setup

Follow the steps in the below sections in the exact order to set up 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` (use this exact name so it matches the workflow below)
- **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**.
{{< /warning >}}

### Step 2: Create Actions workflow

Create the following workflow in your `.github/workflows/` directory:

```yaml
name: Manage Rudder CLI projects

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Project Files
        uses: rudderlabs/rudder-cli-action@v1.4.0
        env:
          RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
        with:
          location: "<path_to_root_project_folder>/"
          mode: "validate"

  apply:
    runs-on: ubuntu-latest
    needs: validate
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Apply Project Files
        uses: rudderlabs/rudder-cli-action@v1.4.0
        env:
          RUDDERSTACK_ACCESS_TOKEN: ${{ secrets.RUDDERSTACK_ACCESS_TOKEN }}
        with:
          location: "<path_to_root_project_folder>/" #Required
          mode: "apply" #Required
```

{{< info >}}
Note that:

- The previous Action `rudderlabs/rudder-tracking-plan-action@v1.0.0` is now deprecated.
- You can update the CLI action version by modifying the `uses` parameter in the workflow file — see the [Rudder CLI Project Manager Action releases](https://github.com/rudderlabs/rudder-cli-action/releases) for the latest version.
{{< /info >}}

Some of the key inputs are described below:

| Input | Description | Default value |
| :----|  :----| :-----|
| `location` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Path to the folder containing the Rudder CLI project files. | - |
| `mode` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | Operation mode — acceptable values are `validate`, `dry-run`, and `apply`. <br /><br />See [Modes](#modes) for more information. | - |
| `cli_version` | Version of the Rudder CLI tool to use. | `v0.10.0` |
| `RUDDERSTACK_ACCESS_TOKEN` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | The [access token](#prerequisites) for the RudderStack workspace. | - |

#### Modes

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

| Value | Notes |
| :---| :----|
| `validate` | <ul><li>Validates Tracking Plan syntax and structure.</li><li>No changes are applied to your configuration.</li></ul> |
| `dry-run` | <ul><li>Simulates the application of changes.</li><li>Shows what would be modified without actually making the changes.</li></ul> |
| `apply` | Applies the relevant changes to your RudderStack workspace. |

If you apply destination or account specs that use `{{ .VAR }}` references, see [How to Use Variable Substitution in Rudder CLI]({{< ref "dev-tools/rudder-cli/variable-substitution.md" >}}).

## How it works

This section explains the GitHub Actions workflow:

- The action only triggers when files in your root project directory are modified.
- The action automatically syncs the changes with RudderStack when you merge them with the `main` branch. It uses the `apply` mode (`mode: apply`) to push the relevant changes.

<br />