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:
The same flow, as steps:
- 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.
- A pull request into
developruns 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. - Merging into
developpublishes 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 fromdevelopto its staging environment, sends events to a Console development environment, which validates them against the draft. - A pull request from
developintomainruns the checks against Console. Merging it publishes the data structures to the production registry and releases the event specifications. Your application, deployed frommainto 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
developbranch and amainbranch, 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: