# Setting Up Your Panther Content Repository

{% hint style="info" %}
This updated `panther_analysis_tool` merge workflow is in open beta starting with Panther version 1.119, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}

## Creating a new Panther content repository

### Prerequisite

* You have installed the Panther Analysis Tool (PAT).

### Step 1: Prepare your Panther repository

* In an empty directory, run `git init` to initialize a Git repository, then run `pat init`.

Prepares your repository for later PAT commands.

The `init` command initializes an empty repository and pulls the latest content from `panther-analysis` to your cache.

### Step 2 (Optional): Explore content from `panther-analysis`

* Run `pat explore`.

### Step 3: Enable content from panther-analysis

To enable content from panther-analysis, like detections, run `pat install`, passing one or more content items. For example:

* `pat install <id>`
* `pat install --filter LogTypes=AWS.CloudTrail`

### Step 4: Ensure new content passes tests

* Run `pat test`.

### Step 5: Upload content to Panther

* Run `pat upload`.

## Migrating from a legacy repository

{% hint style="info" %}
If your existing Panther content repository was [forked or cloned from `panther-analysis`](https://docs.panther.com/panther-developer-workflows/detections-repo/setup/deprecated), migrate to the new management workflow by following the steps below.
{% endhint %}

### Step 1: Prepare your Panther repository

* In your Panther content directory, run `pat init`.

### Step 2: Format existing content

Certain formatting changes to your YAML files are required (such as removing braces and brackets from nested JSON segments, like detection unit tests). To make these changes:

* Run `pat fmt`.

{% hint style="warning" %}
It's recommended to commit changes at this step, as `pat fmt` will generate large amounts of formatting changes that will be tedious to review.
{% endhint %}

### Step 3: Update existing content

Migrate all analysis items that are based off panther-analysis content by adding a `BaseVersion` field and merging them with the most recent panther-analysis version. If your repo is still forked from `panther-analysis` after migrating, that will not break other PAT commands, but we recommend never syncing from upstream `panther-analysis` after migrating. Any automation doing that should be removed.&#x20;

* Run `pat migrate`.&#x20;

{% hint style="info" %}
Note that `pat migrate` does not pull in any new `panther-analysis` content—it only migrates your existing content.
{% endhint %}

### Step 4: Review `migration_status.md` and resolve individual merge conflicts

1. Run `less migration_status.md`.
2. (Optional) If `migration_status.md` indicates there are outstanding merge conflicts, for each item with a conflict, run `pat migrate <ID>` to resolve it.&#x20;
   * You can optionally use `--write-merge-conflicts` to instruct PAT to instead write merge conflicts to the file, which may be useful if you're using AI to solve conflicts or use `--auto-accept` to auto resolve.

     <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>This step is optional because it is not required to resolve merge conflicts before moving on (i.e., before testing and uploading the content that did <em>not</em> generate merge conflicts).</p></div>

   * To resolve a conflict in a YAML file, you'll use the PAT CLI editor.
     * To resolve a conflict in a Python file, you can either use the PAT CLI editor or a code editor of your choice. To designate your code editor of choice (e.g., `code` (VS code), `cursor`, `Poland`, `goland` (Go), `pycharm`), either:&#x20;
       * Use `--editor` with `pat migrate`
       * Set the `EDITOR` environment variable

{% hint style="info" %}
It's also recommended to commit at this stage, before enabling new content.
{% endhint %}

### Step 5 (Optional): Explore latest content from `panther-analysis`

* Run `pat explore`.

### Step 6 (Optional): Enable new content from `panther-analysis`

To enable content from panther-analysis, like detections, run `pat install`, passing one or more content items. You do not need to run the `migrate` command in order to install content you have never had before. For example:

* `pat install <id>`
* `pat install --filter LogTypes=AWS.CloudTrail`

### Step 7: Ensure content passes tests

* Run `pat test`.

### Step 8: Upload content to Panther

* Run `pat upload`.

### Step 9: Remove unused `panther-analysis` content

In the deprecated management workflows, you pulled in all content from panther-analysis, regardless of whether you enabled it or not. In the updated workflow, you only need to keep content you are actually using.

At this stage, you can remove any content that has no use in your environment. When removing content, be sure to run `pat test` frequently to validate that no dependencies have been removed, as detection content often depends on global helpers and data models.