{% callout type="info" heading="" %}
This workflow requires [Ampli CLI 1.9.0+](/docs/sdks/ampli/ampli-cli).
{% /callout %}
Larger organizations with multiple teams usually need to make changes to their tracking plan and analytics implementations in parallel.

This page covers how to use branches in Ampli with source control systems such as Git.

## Workflow summary

When you need to update the tracking plan:

1. Create a branch in Amplitude Data. Make tracking plan updates.
2. Create a branch in Git.
3. Pull the latest generated code for your Data branch into your Git branch with `ampli pull`.
4. Implement the changes using the Ampli Wrapper in your code on your Git branch.
5. Check implementation status with `ampli status`.
6. Merge the Data branch.
7. Check merge status with `ampli status --is-merged`.
8. Merge the Git branch.

## Branches in Ampli

### Ampli CLI

The Ampli CLI can pull generated Ampli Wrapper code for sources and branches you create in Data.

The first time you run `ampli pull` you're prompted to select a Source and Branch from your tracking plan.
The command creates an `ampli.json` file to store your configuration for future development.

```bash
ampli pull
Ampli project is not initialized. No existing 'ampli.json' configuration found.
? Create a new Ampli project here? Yes
Organization: Amplitude Website (Portfolio)
? Select a workspace: Data
? Select a source: browser
Source: browser
Runtime: Browser/TypeScript
? Select a branch: feature-branch-name
✔ Pulling version 74 (latest)
```

If you want to change branches later, use one of the following options.

#### `ampli checkout [my-branch-name]`

This command pulls the specified branch from Data to your Ampli Wrapper. If you don't specify a branch name, Ampli prompts you to select one from a list of active branches in your tracking plan.

```bash
ampli checkout
? Select a branch
  feature-branch-name (current)
  add-products-to-cart
❯ remove-old-forms
  new-registration-metrics
(Move up and down to reveal more choices)
```

#### `ampli pull -b my-branch-name`

The `--branch` flag on `ampli pull` sets the tracking plan to use for the generated source code.

```bash
ampli checkout feature-branch-name
Source: browser
Runtime: Browser/TypeScript
Branch: feature-branch-name
✔ Pulling version 74 (latest)
All events are up to date.
```

### ampli.json

The `ampli.json` file contains configuration information for the Ampli CLI, including the current branch and version. Running `ampli pull` and `ampli checkout` updates `ampli.json` based on the selected tracking plan.

```json title="ampli.json"
{
  "OrgId": "12345",
  "WorkspaceId": "my-workspace-id",
  "SourceId": "my-source-id",
  "Runtime": "node.js:typescript-ampli"
  "Path": "./path/to/ampli",
  "Branch": "main",
  "Version": "1.0.0",
}
```

{% callout type="note" heading="" %}
The Ampli CLI manages this file. Don't modify `ampli.json` by hand. The file remains mostly human-readable to make potential merge conflicts easier to understand.
{% /callout %}

## Coordination and enforcement

The Ampli CLI provides checks to help teams coordinate development across branches.

### `ampli status`

In addition to verifying tracking plan implementation status in your source code, the status command includes checks for branching functionality.

### Example branch structure

```bash
b1           1 -> 2 -> 3
            /            \
main       1      ->      2    ->   3
           \ \                     /
b2          \ 1 -> 2 -> 3 -> 4 -> 5
             \
b3            1 -> 2 -> 3 -> 4
```

### Check whether someone merged the current Ampli branch

`ampli status --is-merged`

```bash
ampli status --is-merged
✔ Verifying event tracking implementation in source code
  ✔ Event A (1 location)
  ✔ Event B (1 location)
✔ All events tracked 2 found, 2 total
⚠ WARNING The current branch branch-mapping version 74 has already been merged into main. Verified implementation against main version 75.
We recommend running ampli pull to update to the latest tracking plan.
✔ Branch branch-mapping version 74 is merged.
```

The `--is-merged` flag checks the current branch and version in your `ampli.json`. If someone merged the exact branch version into Ampli main, the command succeeds. Otherwise, the command exits with error code 1. The command always returns success for the Ampli `main` branch.

For the [branch structure example](#example-branch-structure), `is-merged` returns success for `b1@3`, `b2@5`, `main@3`, `main@2`, and `main@1`.

### Check whether the current Ampli branch uses the latest version

`ampli status --is-latest`

```bash
ampli status --is-latest
✔ Verifying event tracking implementation in source code
  ✔ Event A (1 location)
  ✔ Event B (1 location)
✔ All events tracked 2 found, 2 total
✔ You are on the latest version of feature-branch-name
```

The `--is-latest` flag checks the branch and version in `ampli.json`. If the version is the latest one published for the branch, the command succeeds. Otherwise, the command exits with error code 1.

For the [branch structure example](#example-branch-structure), `is-latest` returns success for `b2@5`, `b3@4`, and `main@3`.

{% callout type="note" heading="" %}
Notice that `b1@3` doesn't pass the `is-latest` check because it maps to an outdated version of `main@2`.

For merged branches, `is-latest` passes only if the branch contains the exact version that corresponds to the latest version of `main`.
{% /callout %}

The `--is-latest-if-not-on-default-branch` flag works the same as `is-latest`, but also returns success for any version of the Ampli `main` branch. Use this flag for CI integrations where you don't want to enforce the latest version on the main branch.

For the [branch structure example](#example-branch-structure), `is-latest-if-not-on-default-branch` returns success for `b2@5`, `b3@4`, `main@3`, `main@2`, and `main@1`.

### Combine checks

When you combine multiple checks `ampli status` returns success only if all checks pass. A failure in any check results in an error exit code.

When multiple checks run, each check outputs its status on a separate line with individual errors and warnings.

### Common errors and solutions

```bash
ampli status --is-merged --is-latest
✘ Verifying event tracking implementation in source code
  ✘ Event A
  ✘ Event B
✘ ERROR Event tracking incomplete 2 missed, 2 total
✘ ERROR Branch feature-branch-name version 73 is not merged.
✘ ERROR Branch feature-branch-name latest version is 74. You are on 73. Run ampli pull to update.
```

Here are some common errors and solutions for the `ampli status` command.

#### Event tracking implementation error

- You haven't correctly instrumented all events in your tracking plan.
- Implement the missing events in your project using the Ampli Wrapper.

#### `is-merged` error

This error means you're on an unmerged Ampli branch. To fix this error:

1. Log into Data and check to make sure your tracking plan has been reviewed and approved.
2. You may need to select **Refresh** on your Data branch before you can merge. If so, run `ampli pull` again to get the latest updates.
3. Merge your Data branch.

#### `is-latest` error

- You aren't on the latest version of your Data branch.
- Run `ampli pull` to update your local project.

### Enforce branch coordination

`ampli status --is-merged --is-latest`

```bash
ampli status --is-merged --is-latest
✔ Verifying event tracking implementation in source code
  ✔ Event A (1 location)
  ✔ Event B (1 location)
✔ All events tracked 2 found, 2 total
⚠ WARNING The current branch feature-branch-name version 74 has already been merged into main. Verified implementation against main version 75.
We recommend running ampli pull to update to the latest tracking plan.
✔ Branch feature-branch-name version 74 is merged.
✔ You are on the latest version of feature-branch-name
```

Use the `ampli status` command to make sure that your Ampli and Git branches stay in sync.

Before you merge your Git branch with implementation changes, verify that both `is-merged` and `is-latest` checks pass. Run `ampli status --is-merged --is-latest`.

{% callout type="info" heading="" %}
Amplitude recommends merging your Git branch immediately after you merge your Data branch. Merging immediately ensures other teams have your implementation of the new events.
{% /callout %}

## CI workflows

Add branch status checks in CI to make sure that code follows best practices.

Amplitude recommends adding status checks to all your PR workflows. In addition to `ampli status -u`\*, add a call to `ampli status --is-merged`.

You can combine these into a single command, but keeping them separate in CI can help identify whether implementation checks succeed independently from branch checks.

- In PR workflows Amplitude recommends using `--skip-update-on-default-branch` when calling `--update` or `-u`.

### Use `is-latest` in CI

Although `is-latest` isn't required, use it in CI workflows for stricter enforcement.

If you use `is-latest` in a multi-team environment or on a tracking plan with multiple sources, you may need extra steps to keep the merge checks passing. Changes merged into the `main` tracking plan by other teams or on other sources cause future runs of `is-latest` to fail in your project because your project is no longer on the latest version.

In this case, you can explicitly lock the tracking plan to a specific version on the `main` branch by using `--is-latest-if-not-on-default-branch`.

Any time an external change happens to the tracking plan, follow these steps:

1. Run `ampli pull` to update `ampli.json` to the `main` branch.
2. Commit changes to Git branch.

After `ampli.json` is on the `main` branch, future calls to `--is-latest-if-not-on-default-branch` pass. The flag behavior keeps the current version fixed regardless of new tracking plan changes.

{% callout type="note" heading="" %}
If you run `ampli pull` on a merged version, Ampli updates `ampli.json` and the Ampli Wrapper to contain the associated main version created by the merged branch. To get the latest version of `main`, run `ampli pull` a second time.
{% /callout %}

## GitHub Actions

### Initial setup

1. Add `ampli-implementation-check.yml` and `ampli-merge-check.yml` to your `.github/workflows` directory.

   ```yaml
   name: Ampli Implementation Check
   on: pull_request

   jobs:
     build:
       runs-on: ubuntu-latest
       container:
         image: amplitudeinc/ampli

       steps:
         - name: Checkout repo
           uses: actions/checkout@v2

         - name: Verify analytics implementation and update status in Data
           run: ampli status -u --skip-update-on-default-branch -t ${{secrets.AMPLI_TOKEN}}
   ```

   ```yaml title="ampli-merge-check.yml"
   name: Ampli Merge Check
   on: pull_request

   jobs:
     build:
       runs-on: ubuntu-latest
       container:
         image: amplitudeinc/ampli

       steps:
         - name: Checkout repo
           uses: actions/checkout@v2

         - name: Check Data branch merge status before merging the Git branch
           run: ampli status --is-merged -t ${{secrets.AMPLI_TOKEN}}
   ```

2. If your Ampli project is in a subdirectory, you may need to set the correct working directory in your Actions. Refer to [GitHub's workflow syntax documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun).

3. Create an API token in Data. Do this from _Settings > API Tokens > Create Token_.

4. Add the API token to your repository secrets as `AMPLI_TOKEN`. Do this from _Settings > Secrets > Actions > New repository secret_.

5. Commit the workflows to your repo. On each PR, Ampli checks both the implementation status and merge status of the current branch in your tracking plan.

### PR workflow

1. During development, the "Ampli Merge Check" in GitHub fails continuously until you merge the corresponding branch in Data. The failure ensures that your code stays in sync with the tracking plan.

2. Start by implementing the latest changes to your tracking plan. The Ampli Implementation Check verifies those changes.

3. After all other checks have passed except the "Ampli Merge Check", you are ready to get approval in GitHub.
4. After GitHub approves your PR, go to <https://data.amplitude.com> and merge your Data branch. Do this under **Home** after selecting the branch in the left-hand dropdown.

{% callout type="warning" heading="" %}
If your Data branch is out of date with the main tracking plan, you may need to select **Refresh** before you can merge. Refresh applies the latest changes from main to your Data branch. If you select **Refresh**, pull the latest changes in both Git and Ampli.
{% /callout %}

5. After you merge the branch in Data, you can re-run the "Ampli Merge Check" in GitHub.
   - Click **Details** next to the failed "Ampli Merge Check - PR" job.
   - Click **Re-run jobs** > **Re-run failed jobs**.

6. After the "Ampli Merge Check" runs successfully, you can merge your Git branch.

## Bitbucket Pipelines, Circle CI, and other CI/CD systems

You can add merge and implementation checks to many different CI workflows with the Ampli CLI. To simplify integration, use the [Ampli CLI Docker containers](https://hub.docker.com/u/amplitudeinc), which are already configured to run the Ampli CLI commands.

Follow the high-level setup to add merge and implementation checks to your CI workflows.

High-level setup:

1. Use an Ampli CLI Docker image to run Ampli CLI commands.
2. Create an API token in Data.
3. Add the API token as a repository or workflow secret.
4. Add an Ampli implementation check to run on PR.
5. Add an Ampli merge check to run on PR.

Refer to the [GitHub Actions](#github-actions) instructions for an example.

## FAQs

### Check Ampli generated code and ampli.json into git

Yes. Check the generated code from Ampli and `ampli.json` into source control. With `ampli.json` checked in, the source code stays pinned to a specific point in time of the tracking plan, and your team shares the Ampli CLI configuration. Check the Ampli generated file into git like any other code in your project.

### Resolve git conflicts in Ampli generated code and ampli.json

No. If you have git conflicts in any Ampli-related files, such as Ampli generated code or `ampli.json`, run `ampli pull`. The Ampli CLI resolves the conflicts automatically.

### Ampli branch references in ampli.json on git main

Yes, that's expected. The Ampli CLI uses this information to verify that the Ampli branch has been merged, for example when automatically resolving git merge conflicts. The information also documents which tracking plan version the most recent tracking plan implementation for this source used. The Ampli CLI automatically updates `ampli.json` on the next `ampli pull`, pinning the file to the new Ampli branch you're pulling from.

### Run ampli pull -b main before merging a Git branch

No. If you used an earlier version of Ampli, update to Ampli CLI 1.9.0+ and pull the latest version of your Ampli Wrapper. After that, you don't need to run `ampli pull -b main` again.