Validate in CI

Amplitude Data works best when integrated into your continuous integration (CI) workflow, running continuously alongside your test suite. We integrate with all common CI providers and can be configured for custom environments.

After you've added Amplitude Data to your CI environment, Amplitude Data will verify your analytics against every build.

Step 1: Create an API token¶

Create an API token in your account or set up another account to be used for CI. Ampli uses this token for authentication when running inside CI to update your tracking plan's implementation status.

Step 2: Configure a CI environment variable¶

Create an environment variable in your CI service called ITLY_KEY and set it to the API token you created. You'll use this environment variable to pass the token to ampli status when it runs inside CI.

For example, this is what the Netlify environment variables screen would look like.

Read the documentation for your CI service to get step-by-step instructions:

• Bitbucket Pipelines
• CircleCI
• GitLab CI
• Jenkins
• Travis CI

Step 3: Prepare your project¶

By now, you've run ampli pull and ampli status in your project's root folder. The folder contains an ampli.json file with metadatata about the current state of the Itly SDK in your project. When you run ampli status, on your local machine or soon in CI, Ampli will verify your analytics against this file.

For non-JavaScript and non-TypeScript projects, this is all the configuration that's needed.

Optionally, for JavaScript and TypeScript projects, you may decide to install Ampli locally as a dev dependency. Installing Ampli locally in the project's node_modules folder simplifies installation and usage of Ampli for your team and CI environment. There are two steps to this.

Install Ampli as a dev dependency¶

To install Ampli locally, run npm install @amplitude/ampli -D.

Step 4: Run Ampli in CI¶

To integrate Ampli with your CI system, modify your CI configuration to run ampli status as part of the build process. We've made it easy by creating Docker Containers that you can use which include dependencies. Some runtimes have their own containers:

• amplitudeinc/ampli
• amplitudeinc/ampli-swift
• amplitudeinc/ampli-dotnet
• amplitudeinc/ampli-all (for convenience this contains everything but is larger in size)

The following examples are for Bitbucket Pipelines but you can use the same images in any CI system that supports containers.

# bitbucket-pipelines.yml
# Runtimes:
# android-java, android-kotlin, browser-javascript, browser-javascript,
# ios-objc, jre-java, node-javascript, node-typescript, python, ruby
- step:
    name: Run 'ampli status' in CI
    image: amplitudeinc/ampli
    script:
      - ampli status [-u] -t $ITLY_KEY

# bitbucket-pipelines.yml
# Runtimes: Swift
- step:
    name: Run 'ampli status' in CI
    image: amplitudeinc/ampli-swift
    script:
      - ampli status [-u] -t $ITLY_KEY

# bitbucket-pipelines.yml
# Runtimes: .NET C#
- step:
    name: Run 'ampli status' in CI
    image: amplitudeinc/ampli-dotnet
    script:
      - ampli status [-u] -t $ITLY_KEY

# bitbucket-pipelines.yml
# Runtimes: Ruby
- step:
    name: Run 'ampli status' in CI
    image: amplitudeinc/ampli-ruby
    script:
      - ampli status [-u] -t $ITLY_KEY

You should now have Ampli running inside your CI system. Congratulations!