Source Control

This page covers how you can 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 is able to pull down generated Ampli Wrapper code for Sources and Branches you have created in Data.

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

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 later you would like to change branches you have a couple of options.

ampli checkout [my-branch-name]

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

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.

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. This includes information about the current
branch and version. Running ampli pull and ampli checkout updates the ampli.json based on the selected tracking plan.

{
  "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",
}

Coordination and enforcement

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

ampli status

In addition to verifying implementation status of the tracking plan in your source code, the status command has some other checks specifically for branching functionality.

Example branch structure

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

Check if current Ampli branch is merged

ampli status --is-merged

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 the exact Version of the Branch was merged into Ampli main it succeeds, otherwise it exits with error code 1. It always return success for the Ampli main branch.

For the branch structure example,, is-merged would return success for b1@3, b2@5, main@3, main@2, main@1.

Check if current Ampli branch is on the latest version

ampli status --is-latest

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 the ampli.json. If the Version is the last one published for the Branch it succeeds, otherwise it exits with error code 1.

For the branch structure example, is-latest would return success for b2@5, b3@4, main@3.

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

For the branch structure example, is-latest-if-not-on-default-branch would return success for b2@5 , b3@4, main@3, main@2, 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 the status of each is output on a separate line with individual Errors and Warnings.

Common errors and solutions

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

• This means 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 means you are currently on an un-merged 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 "Refresh" your Data branch before being able to merge. If so make sure to run ampli pull again to
   get the latest updates.
   Merge your Data branch.

is-latest error

• This means 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

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

You can make sure that your Ampli and Git branches stay in sync with the ampli status command.

Before merging your Git branch with implementation changes you should verify that both is-merged and is-latest checks pass successfully. You can do this with a single command ampli status --is-merged --is-latest.

CI workflows

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

Amplitude recommends adding new status checks to all your PR workflows. In addition to ampli status -u* you should add also add a call to ampli status --is-merged.

You can combine these into a single command, but for CI it can be useful to keep them separate. This helps you to see if the implementation checks succeed independently from the branch checks.

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

Use is-latest in CI

Although it's not required, use is-latest in CI workflows for stricter enforcement.

If you use is-latest in a multi-team environment or on a tracking plan with multiple Sources it can require extra steps to keep the merge checks in a passing state. Changes merged into to the main tracking plan by other teams or on other Sources cause future runs of is-latest to fail in your project. This is because it's no longer on the latest version.

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

This means any time an "external" change happens to the tracking plan you must follow these steps:

1. Run ampli pull to update the ampli.json to be on the main Branch.
2. Commit changes to Git branch.

After the ampli.json is on the main branch future calls to --is-latest-if-not-on-default-branch pass. This is useful to keep the current version fixed regardless of new tracking plan changes.

GitHub Actions

Initial setup

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

   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 $
   

2. If your Ampli project is in a subdirectory, you may need to set the correct working-directory in your Actions. See GitHub documentation here.

3. Create a API token in Data. Do this from Settings => API Tokens => Create Token.

4. Add the API token to your Repository secrets as AMPLI_TOKEN. You can do this from
   Settings => Secrets => Actions => New repository secret

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