Skip to main content
Data governance
Composable analytics

Manage tracking as code with Snowtype and Snowplow CLI

Keep data structures and tracking plans in your application's repository, generate tracking code with Snowtype, and check and publish every change with Snowplow CLI and GitHub Actions.

Progress0%

For AI agents: a Markdown version of this page is at https://docs.snowplow.io/tutorials/tracking-as-code/introduction.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt.

Manage tracking as code with Snowtype and Snowplow CLI

This tutorial shows you how to manage your tracking from your application's own repository. The data structures and the tracking plan live as files next to the code that sends the events. Snowtype generates the tracking code from those files, and Snowplow CLI checks every change and publishes it to Console from GitHub Actions.

Managing tracking this way gives every change to your tracking a pull request, a review, and a history, in the same place as the code change that needs it. The checks catch a tracking definition and its generated code drifting apart, and an event specification version that doesn't match the version Console assigns, before anything reaches Console.

Most of the work runs on your machine and in pull request checks that need no Console access: you write the definitions, generate the code, and check the versions offline. You only need Console access when GitHub Actions checks a pull request against Console and publishes the merged tracking.

This tutorial is for developers who already track events with the JavaScript tracker and want their tracking definitions under version control. You'll work in your own terminal and in a GitHub repository.

What you'll build​

You'll set up one repository that holds the tracking for a TypeScript web app, and the workflows that check and publish it. The example tracks one self-describing event, signup, with one entity, plan, through one event specification, Signup, in a tracking plan called Signup flow.

This tutorial follows one example path, with a develop and a main branch. A single branch works too, without the step where you test a draft before it's released. Adapt the branch names to your own workflow:

flowchart TB F[Feature branch] -->|pull request| D[develop] D -->|pull request| M[main] D -.->|your app's deployment| SA[Your app in staging] M -.->|your app's deployment| PA[Your app in production] SA -->|sends events to| Q[Console development environment] PA -->|sends events to| P[Your production pipeline] D -->|publishes drafts to| O[Your Snowplow organization] M -->|publishes and releases to| O

The same flow, as steps:

  1. You change the tracking definitions and the code on a feature branch, regenerate the tracking code with Snowtype, and check the versions locally without credentials.
  2. A pull request into develop runs the local checks again, and adds the checks against Console, which catch what the local checks can't see, such as a change that reached Console from another branch.
  3. Merging into develop publishes the data structures to the development registry and syncs the tracking plan, so a changed event specification gets a new draft version. Your application, deployed from develop to its staging environment, sends events to a Console development environment, which validates them against the draft.
  4. A pull request from develop into main runs the checks against Console. Merging it publishes the data structures to the production registry and releases the event specifications. Your application, deployed from main to production, sends events to your production pipeline.

Nothing reaches the production registry or the production pipeline until it merges into main. The tracking plan belongs to your organization, not to a pipeline, so both branches publish the same tracking plan: develop leaves new versions in draft, and main releases them.

Requirements​

To follow this tutorial, you need:

  • A GitHub repository for your application, with a develop branch and a main branch, and GitHub Actions enabled
  • A TypeScript web app that uses the JavaScript tracker (@snowplow/browser-tracker), with Node.js and npm installed
  • Snowplow CLI installed
  • Snowtype installed in the app as a development dependency
  • A Snowplow account with Console and a development environment, for the checks against Console and the publish workflow
  • Familiarity with Git and GitHub Actions

Snowplow CLI must be a version that checks event specification versions, and Snowtype a version that generates code from local tracking plans and has the check command:

Applies to Snowplow CLI 0.4.0+Latest: 0.5.0 Applies to Snowtype 0.20.0+Latest: 0.21.0