Integrating with CI

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

Once you've added Iteratively to your CI environment, Iteratively will verify your analytics against every build.

note

Iteratively checks your analytics implementation against the tracking plan version that's currently checked in. If your team made changes to your tracking plan since the last call to itly pull, those changes will not cause a failure in CI.

Step 1: Create an API token#

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

IMPORTANT

Keep your token secret. Your token has global permissions on your account.

Tokens

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 in Step 1. You'll use this environment variable to pass the token to itly verify when it runs inside CI.

For example, this is how it would work in Netlify.

Netlify Environment Variables

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

Step 3: Prepare your project#

By now, you've run itly init, itly pull, and itly verify in your project's root folder. The folder contains an .itlyrc file with metadatata about the current state of the Itly SDK in your project. When you run itly verify, on your local machine or soon in CI, Itly 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 Itly locally as a dev dependency. Installing Itly locally in the project's node_modules folder simplifies installation and usage of Itly for your team and CI environment. There are two steps to this.

Install Itly as a dev dependency#

To install Itly locally, run npm install @itly/itly -D or yarn add @itly/itly -D.

Step 4: Run Itly in CI#

To integrate Itly with your CI system, modify your CI configuration to run itly verify as part of the build process. We've made it easy to by creating Docker Containers that you can use which include dependencies. Some runtimes including ios-swift, dotnet-c-sharp, and ruby have thier own containers.

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

The itly-verify image can be used to verify the following SDK runtimes.

  • android-java
  • android-kotlin
  • browser-javascript
  • browser-typescript
  • ios-objc
  • jre-java
  • node-javascript
  • node-typescript
  • python (2 & 3)
# bitbucket-pipelines.yml
# Runtimes:
# android-java, android-kotlin, browser-javascript, browser-javascript,
# ios-objc, jre-java, node-javascript, node-typescript, python
- step:
name: Run 'itly verify' in CI
image: iteratively/itly-verify
script:
- itly verify [-u] -t $ITLY_KEY

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