Tracking Agent docs

How to set up the Tracking Agent

Set up the Tracking Agent in the browser: buy a plan, connect GitHub, choose model and analytics access, set the rules, then install. Installing opens a setup pull request, and the install audit runs on it and drafts your tracking plan from the code. datalyze init runs the same steps in a terminal.

• A Datalyze account with the Tracking Agent or the bundle. Only the person who pays needs one; reviewers sign in with GitHub.
• Admin access to the GitHub repo, so setup can save secrets, add the workflow, create a GitHub App and make the checks required.
• Model access: an API key, an organisation secret, a cloud identity on AWS Bedrock or Google Vertex, or an AI gateway. See models.
• A TypeScript, JavaScript, Swift, Kotlin or Dart codebase. Mobile apps need a little more config: see mobile apps.
• Optional: read access to your analytics tool, and a Google Sheet.

1. Buy a plan. Sign up or sign in, then choose the Tracking Agent ($100 a month) or the bundle with the Datalyze MCP ($125 a month).
2. Create a workspace and connect GitHub. Sign in with GitHub and pick the repos to check.
3. Choose model access: a provider and key, the name of an organisation secret, a cloud identity, a gateway, or set it up yourself later.
4. Choose analytics access: your tool and a read-only key or service account. Mixpanel, PostHog and Amplitude have recipes; see connecting analytics. For a warehouse, also say where the events are and which SDK your app sends them with.
5. Connect a Google Sheet (optional): copy the Datalyze template and paste its receiver URL and token, or use a Google service account. See the Google Sheet.
6. Set the rules: reviewers and signers (GitHub logins or teams written @org/team), whether pull request authors may approve their own tracking, and your platforms. For a mobile app, also how you cut a release, so the post-release watch knows which version ships a change. For a repo in an organisation, setup gives your App read access to the organisation's members, so team entries work.
7. Install. Setup creates your own GitHub App, saves every secret to the repo encrypted in your browser, opens the setup pull request, and makes datalyze/tracking and datalyze/rules required checks on your default branch, accepted only from your App.
8. Read the install audit. It runs on the setup pull request and commits the drafted registry, the baseline, the typed tracker and a report to it. Merge once you've read the report.

Setup starts from the Datalyze default conventions: snake_case object_action event names such as post_created. Change them in analytics/registry/_conventions.yaml, in the setup pull request or later. The playbook chapter on creating a tracking plan covers choosing a naming convention.

The install audit then adds the rest of the registry, _baseline.json, the typed tracker in analytics/generated/ and a report, as commits on the same pull request. Nothing in your product code changes.

When a call builds its event name at runtime, such as from a map of steps to names, and each name appears as a string in the code, the install audit records those names as scan.dynamic_names, so the events reach the registry. Properties a wrapper adds to every event on the client or the server are declared once, as super properties.

The install audit runs only on the first setup pull request: a pull request from the branch datalyze/setup gets it when its base branch has no .datalyze/config.yaml yet. After setup has merged, a branch with that name is an ordinary pull request and gets the normal check.

Each value is encrypted in your browser with the repo's public key and sent straight to GitHub, so none of them reaches Datalyze's server. GitHub explains how secrets in GitHub Actions are stored and who can read them.

datalyze init asks the same questions in the terminal and writes the same workflow, config, conventions and README, saves the same secrets, and opens the same setup pull request. Run in a mobile app's checkout, it also finds the app and proposes its typed tracker and generated unit tests. Run datalyze init --help for its options.

npx datalyze init

To set up by hand instead: datalyze workflow --action <owner/repo/path@ref> writes .github/workflows/datalyze.yml, and datalyze github-app create creates your GitHub App and saves its two secrets. [ANSH: confirm the CLI's install command once the package is published]

Commits pushed with the default Actions token don't start other workflows, so your CI would never run on the agent's commit and its required checks would wait forever. GitHub documents this in automatic token authentication. Commits pushed with your own App's token do start them.

The App belongs to your account, is installed only on the repos you choose, and its private key lives in your repo's secrets. Without it the agent still works, and its report says your CI won't run on its commits.

The App also decides who can post the required checks. With it, the ruleset accepts datalyze/tracking and datalyze/rules only from your App; without it, any token with write access to the repo could post them.

One risk is left either way. Anyone who can push a branch that changes .github/workflows/ can run code with the repo's secrets on that pull request, the App's key included. Protect .github/workflows/ and .datalyze/ with CODEOWNERS and turn on required code-owner review for your default branch, so a change to either can't merge without its owner's review, and give write access only to people you'd trust with those secrets.