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 every time a CI build runs.

When verifying analytics in CI, 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 mates and your CI environment. There are two steps to this.

Create an .npmrc file

Since Itly is not yet available in the public NPM registry, you'll need to point npm (or yarn) to the right place. To do this, create an .npmrc file next to your package.json:

@itly:registry=https://repo.iterative.ly/npm/
//repo.iterative.ly/npm/:_authToken={token}

The Iteratively team will provide you with a token.

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 a CI system, modify your CI configuration to run the verify command as part of the build process. To do this:

  • If it's not already available, install node. This will also install npm.
  • Install Itly with npm install -g @itly/itly --registry https://npm-proxy.fury.io/{token}/itly. You can skip this step if this is a JavaScript or TypeScript project and @itly/itly is a dev dependency.

    The Iteratively team will provide you with a token.

  • Run itly verify -t $ITLY_KEY. If you're checking into or merging into your production branch, run itly verify -u -t $ITLY_KEY to also update the implementation status in your tracking plan.

The exact steps to take will depend on your CI system. The example here shows what this would look like for a typical JavaScript/TypeScript project and Bitbucket Pipelines.

First, add the Itly command to your project's package.json:

"scripts": {
"itly-ci-pr": "itly verify -t $ITLY_KEY",
"itly-ci": "itly verify -u -t $ITLY_KEY"
}

The itly-ci-pr script is configured to authenticate using an API token, rather than the token stored in ~/.itlyrc, but not to update the implementation status. The goal of the command in this context is to verify that analytics is implemented correctly prior to a merge.

The itly-ci script is configured to authenticate using an API token and update the implementation status in the tracking plan. This script runs when your code is merged into the branch from which it gets deployed to production (in our example here, that branch is master).

Next, add the new steps to your project's Bitbucket Pipelines configuration file bitbucket-pipelines.yml:

pipelines:
pull-requests:
'**':
- step:
script:
- yarn itly-ci-pr
branches:
master:
- step:
script:
- yarn itly-ci

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