Tracking Agent docs

The Tracking Agent Google Sheet: tabs and notes

The Google Sheet is a read-only view of your tracking plan, rebuilt from the registry after every merge to your default branch. It has five tabs. On the plan tabs, two columns belong to people, Verified in <tool> and Analyst Notes, and every rebuild keeps them.

By Ansh AgrawalUpdated

What's on each tab of the tracking plan Sheet?

TabWhat's on itWho edits it
Tracking PlanEvery live and planned event, one row per propertyThe sync, except Verified in <tool> and Analyst Notes
User PropertiesEvery live and planned user propertyThe sync, except the same two columns
Super & Group PropertiesProperties sent on every event, and group propertiesThe sync
DeprecatedDeprecated events and user properties with the reason, replaced_by and date, plus orphaned notesThe sync, except the same two columns
ChangelogEvery registry change, with the pull request and the GitHub login of who approved itThe sync

The Question column is empty for items with no business question, since the question is optional. The approver on the Changelog comes from the pull request's proposal file.

How does the Sheet work out each item's status?

On every sync, from a scan of the code on your default branch. The registry only says what people intend, planned or deprecated; whether an item is actually in the code is worked out each time and never written back to the registry.

  • implemented: live in the plan, and the call is in the code.
  • not implemented: live in the plan, but no call is in the code.
  • external: marked as sent by another service.
  • planned and planned, already firing: still planned, without or with a call in the code.

Whether data actually arrives is the audit's job: the audit results are on the audit screen in Datalyze, not in the Sheet.

Which Sheet columns can people edit?

On the plan tabs, Verified in <tool> (named for your analytics tool, such as Verified in Mixpanel) and Analyst Notes. A person marks an item verified after seeing its data arrive with the right properties; nothing else sets it.

Each rebuild reads those two columns first and writes them back to the same row, keyed by event and property, however the rows move. If a row goes away because a property was removed or an event deprecated, its note moves to the Deprecated tab as an orphaned note, with the date, rather than being lost. The playbook chapter on event verification covers what to check before marking an event verified.

How do I connect a Google Sheet to the Tracking Agent?

Share the Sheet with Datalyze's service account as an Editor, then paste its link in Datalyze, in onboarding's Google Sheet step or on the Setup page. There's no script to deploy and no secret to add.

  1. Open your Google Sheet, press Share, and add the email Datalyze shows you as an Editor.
  2. In Datalyze, paste the Sheet's link next to the repo and press Connect. Use a separate Sheet for each repo.
  3. Datalyze checks it can open and edit the Sheet before saving it. The Sheet fills after the next merge to your default branch.

Connect refuses a Sheet that isn't shared with Datalyze, is shared only to view, or isn't a Google Sheet (an uploaded .xlsx file), and says what to change. With this route, your plan's rows pass through Datalyze's server on their way to Google and aren't stored: Datalyze keeps only the Sheet's name, who shared it, and when it last synced.

How do I connect the Sheet if our Google account can't share outside the company?

Use the Datalyze template's Apps Script receiver. The sync then goes straight from your GitHub runner to your Sheet, without passing through Datalyze.

  1. Make a copy of the Datalyze Sheet template.
  2. In your copy, open the Datalyze menu and choose Connect. Allow the script to edit this spreadsheet. Connect makes a token and creates the five tabs.
  3. In the Apps Script editor, deploy the script as a web app: Deploy, then New deployment, type Web app, execute as Me, access Anyone.
  4. Add the web app URL (it ends in /exec) and the token to the repo's Actions secrets as DATALYZE_SHEET_URL and DATALYZE_SHEET_TOKEN.

Access has to be "Anyone" because the sync runs on GitHub's runner, which can't sign in to Google. The script answers only requests that carry the token, and runs as you, so it can reach only this Sheet. When both secrets are set, the sync uses them, even if a Sheet is also connected in Datalyze. To use other secret names, set them in .datalyze/config.yaml:

yaml
# .datalyze/config.yaml
sheet:
  url_env: DATALYZE_SHEET_URL
  token_env: DATALYZE_SHEET_TOKEN

An older config with sheet.mode: service_account now stops the sync with a "no longer supported" error. Remove the sheet key and connect the Sheet in Datalyze instead.

When does the Tracking Agent Sheet update?

After every push to your default branch, the workflow rebuilds it from the registry on that branch. A failed sync never blocks a pull request or a merge: it's tried once more, and if that fails too, only that run fails and the Sheet stays as it was until the next merge. To rebuild it by hand, open the latest Datalyze run on your default branch in the Actions tab and choose Re-run all jobs.

The Setup page shows when each repo's Sheet last synced, and the error if the last sync failed. A repo with no Sheet connected skips the sync and nothing fails. Sheets made before October 2026 may still have Plan Health, Audit, Pending Changes or Requests tabs; the sync no longer fills them, marks each with a note, and never deletes a tab.

Questions about the Google Sheet

Can we edit tracking in the Google Sheet?

No. The registry in your repo is the source of truth, and the sync rewrites the plan tabs from it. Change the registry in a pull request, and the Sheet follows after it merges.

Do we need the Google Sheet at all?

No. It's optional, for people who'd rather read a spreadsheet than YAML. The PR check and the audit work the same without it.

Does our Sheet data go through Datalyze?

Yes, when you connect the Sheet by sharing it with Datalyze: the plan's rows pass through our server on their way to Google and aren't stored. With the Apps Script route, they go straight from your GitHub runner to your Sheet.

We don't have a tracking plan to put in a Sheet yet. Where do we start?

The free event tracking plan generator drafts one, and our analytics setup service builds it with you.