# Automate Project Management with Rudder CLI and GitHub Actions


> Leverage GitHub Actions for automating management of your Rudder CLI projects.



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](https://www.rudderstack.com/docs/access-management/service-access-tokens/#workspace-sat) in the RudderStack dashboard with the following [permissions](https://www.rudderstack.com/docs/access-management/policies-overview/#resource-permissions) to manage Data Catalog and Tracking Plans:

| Resource | Permissions |
| --- | --- |
| Tracking Plans | **Create & Delete**, **Edit** |
| Data Catalog | **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 minimum **Admin** permissions.

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 Admin permission](/docs/images/access-management/permissions/legacy/admin.webp)

## 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**.

### 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.

Some of the key inputs are described below:

| Input | Description | Default value |
| :----|  :----| :-----|
| `location` <br/> Required | Path to the folder containing the Rudder CLI project files. | - |
| `mode` <br/> Required | 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/> Required | 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](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## 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 />