Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

# Skill trees owned by product teams.
/context/skills/error-tracking-upload-source-maps/ @PostHog/team-error-tracking
/context/skills/error-tracking-link-releases/ @PostHog/team-error-tracking
/context/skills/self-driving/ @PostHog/team-self-driving
/context/skills/data-warehouse-source/ @PostHog/team-warehouse-sources
/context/skills/mcp-analytics/ @PostHog/team-mcp-analytics
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,7 @@ review to their owning team instead.
| `*` (everything else, including all other skills) | `@PostHog/team-wizard-docs` |
| `context/skills/integration/` | `@PostHog/team-wizard-docs` |
| `context/skills/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
| `context/skills/error-tracking-link-releases/` | `@PostHog/team-error-tracking` |
| `context/skills/mcp-analytics/` | `@PostHog/team-mcp-analytics` |
| `context/skills/revenue-analytics/` | `@PostHog/team-web-analytics` |
| `context/skills/self-driving/` | `@PostHog/team-self-driving` |
Expand Down
79 changes: 79 additions & 0 deletions context/agents/error-tracking/link-releases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
type: link-releases
flow: error-tracking
label: Link deploys to releases
model_pi: openai/gpt-5.6-sol
effort_pi: medium
model_sdk: claude-sonnet-5
effort_sdk: high
skills: []
allowedTools: [Read, Write, Edit, Glob, Grep, Bash, load_skill_menu, install_skill, detect_package_manager]
disallowedTools: [enqueue_task]
dependsOn: [capture-exceptions]
---

## Goal

Link every exception this app sends to the production release it came from.
This platform ships its source as is, so there is nothing to upload. Instead the
production deploy resolves a PostHog release, and the app starts with that
release's ID in `POSTHOG_RELEASE_ID`. Install the skill your task input names
(`install_skill` with the `skillId`) and follow it. It owns the minimum SDK
version, the CI step per provider, and how the ID crosses each deploy boundary.

Your task has three parts, in this order:

1. **SDK version.** Make sure the project resolves at least the SDK version
Comment thread
ablaszkiewicz marked this conversation as resolved.
Resolved
that reads `POSTHOG_RELEASE_ID`, per the skill's "Update the SDK" step. An
older SDK ignores the variable without an error. Refresh the lock for that
one package with the project's own tool: call `detect_package_manager`
first. Do not upgrade across a major version when code from before this run
already calls the SDK; when the `install` handoff says this run added the
SDK, raise it straight to the minimum. The production runtime
decides what can install, not the interpreter on this machine: never lower
the version below the minimum because a local install fails.
2. **Resolve the release in the production deploy.** Trace the deploy path by
reading the project's own files: CI workflows, Dockerfiles, compose files,
deploy scripts, service and pool configs. Add the resolve step to the job
that deploys to production, and to no other job.
3. **Get the ID into the running app.** Pass the ID on at every boundary
between that step and the process that creates the PostHog client, until
that process starts with `POSTHOG_RELEASE_ID` in its environment.

## Local development stays as it is

This is a deploy-time change only. Local runs, tests, pull-request builds, and
previews send no release ID, and that is correct. So do not touch run scripts,
dev servers, test config, `.env`, or `.env.example`. Do not ask for a personal
API key, because nothing local uses one. Never run `posthog-cli` yourself: a
resolve creates a real release in the user's project.

Only edit CI and deploy files that already exist. When this project has no
deploy path you can open and follow, make no CI changes. Report the task done
with the SDK update alone, and put the requirement into your handoff as a
manual follow-up.

## The last hop decides it

A release ID that stops one boundary short of the app looks correct in the
diff and does nothing. The resolve step succeeds, the deploy is green, and
every exception still arrives without a release. Each of these boundaries drops
the value unless you pass it on: a `docker build`, a container start, an SSH
session, a service manager's environment, PHP-FPM's `clear_env`, and Laravel's
cached config. So walk the path to its end, and pass the value on the same way
the deploy already passes the app's other runtime variables.

While you are at the start step, check the other names on it too. The app's
PostHog init reads a token and a host, and the start step may predate PostHog.
If it passes the app's variables by hand and leaves those out, add them by the
names the app's source reads, and name any secret the user must create.

## How you know you succeeded

The project resolves an SDK version that reads `POSTHOG_RELEASE_ID`, or your
handoff names the upgrade as a follow-up. The production deploy job resolves
the release before it ships, without failing the deploy when PostHog cannot be
reached. The ID reaches the app process as `POSTHOG_RELEASE_ID`, and no local,
test, or pull-request path changed. Your handoff lists the files you changed,
the SDK version before and after, the deploy path hop by hop, and every secret
and variable the user must create, with its exact name and where it goes.
40 changes: 28 additions & 12 deletions context/agents/error-tracking/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,16 @@ effort_sdk: medium
skills: []
allowedTools: [Read, Glob, Grep, Write]
disallowedTools: [enqueue_task]
dependsOn: [capture-exceptions, wire-ci]
dependsOn: [capture-exceptions, wire-ci, link-releases]
---

## Goal

Tell the user what error tracking now does for them and what they still have
to do, from the handoffs of every task in the run. `read_handoffs` gives you
each task's report β€” the capture mechanism, the files changed, the env
variable names, the CI secret to create, and any deploy path that could not be
traced. Do not re-derive any of it from the project.
variable names, the CI secrets and variables to create, and any deploy path
that could not be traced. Do not re-derive any of it from the project.

Write the hand-off to `posthog-error-tracking-report.md` at the top level of
this project's directory. When any handoff carries a manual follow-up, START
Expand All @@ -30,17 +30,22 @@ item. The wizard shows these bullets again when it exits.
> - Load `.env` in the app, or set `POSTHOG_API_KEY` in its environment.
```

Then, when the run wired source-map upload or any follow-up has steps, add a
**"What you still need to do"** section β€” numbered, copy-pasteable:
Then, when the run wired source-map upload or release linking, or any
follow-up has steps, add a **"What you still need to do"** section β€” numbered,
copy-pasteable:

1. Create a personal API key with the 'Source map upload' preset at
`<UI_HOST>/settings/user-api-keys` (skip when the credentials handoff says
the key is already written).
2. Add it as the CI secret the wire-ci step referenced, named exactly as in
the pipeline config.
the key is already written and no release linking was wired). The preset
carries the error tracking write scope that both uploads and release
linking need.
2. Add it as the CI secret the wire-ci or link-releases step referenced, named
exactly as in the pipeline config. When link-releases also reads a project
ID variable (such as `POSTHOG_PROJECT_ID`), add it with the value
`<PROJECT_ID>`, and say where each goes in the CI provider's settings.
3. Any other manual follow-up the handoffs carry (an env file nothing loads,
an untraceable deploy path, provider-side settings, installing a missing
`posthog-cli`).
`posthog-cli`, an SDK upgrade across a major version).

Then cover, briefly and concretely:

Expand All @@ -58,9 +63,20 @@ Then cover, briefly and concretely:
- When it was skipped: one line saying why β€” readable stack traces on this
platform, or that Astro is not supported by the uploader. An outcome, not an
apology. Say plainly that the build command was left untouched.
- When release linking was wired: the files changed (paths only), the SDK
version it now requires, and the deploy path the release ID takes to the
app. Say that each production deploy resolves a release and starts the app
with `POSTHOG_RELEASE_ID`, so every exception names the release, version, and
commit it came from. Say plainly that local runs, tests, and pull-request
builds are unchanged and send no release ID. When the link-releases handoff
reports no deploy path it could follow, say what the user's deploy must do
instead.
- How to verify: trigger any error and look at
`<UI_HOST>/project/<PROJECT_ID>/error_tracking`; uploaded symbol sets appear
at `<UI_HOST>/project/<PROJECT_ID>/error_tracking/configuration`.
at `<UI_HOST>/project/<PROJECT_ID>/error_tracking/configuration`. With
release linking, check after the next production deploy that the stack trace
shows the release, and that the exception's `$release_id` matches the ID the
deploy resolved.

Never write a secret value into the report β€” only variable names. Replace
`<UI_HOST>` and `<PROJECT_ID>` from your project context. Give the same
Expand All @@ -70,5 +86,5 @@ summary in chat, warning block first.

`posthog-error-tracking-report.md` exists and a user who reads only it knows
how errors reach PostHog, the follow-ups they still owe (the API key and the
CI secret named exactly, when upload was wired), and where in PostHog to see
the first captured exception.
CI secrets and variables named exactly, when upload or release linking was
wired), and where in PostHog to see the first captured exception.
72 changes: 53 additions & 19 deletions context/agents/error-tracking/setup-error-tracking.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,13 @@ dependsOn: []
## Goal

Plan a PostHog Error Tracking setup and seed the task queue. The end state:
errors the app does not catch reach PostHog, and β€” where the platform ships
minified bundles or stripped binaries β€” production builds upload the source
maps or debug symbols that make the stack traces readable.
errors the app does not catch reach PostHog; where the platform ships minified
bundles or stripped binaries, production builds upload the source maps or debug
symbols that make the stack traces readable; and where the platform runs its
source as is (Python, Ruby, PHP), each production deploy links its errors to a
release.

First establish two facts from the repo:
First establish three facts from the repo:

**1. Is PostHog already integrated?** Look for `posthog-js` or a server SDK in
the dependency manifests, or a `posthog.init(...)` / snippet in the source.
Expand Down Expand Up @@ -64,20 +66,45 @@ and pick at most one, by this precedence (first match wins):
- **none** for platforms whose stack traces are already readable: plain
Python (Django, Flask, FastAPI), Ruby, PHP, Elixir, JVM servers, .NET.
Skip the whole upload subgraph for them β€” a skipped upload on such a
platform is an outcome, not a gap.
platform is an outcome, not a gap. Fact 3 decides what Python, Ruby, and
PHP get instead.

When a variant matched, the uploader skill id is
`error-tracking-upload-source-maps-<variant>`. Pass it to the four upload
tasks as `inputs: { skillId: "<id>", displayName: "<human platform name>" }`
so no task re-detects.

The two facts are independent β€” settle BOTH before you enqueue anything.
"PostHog is already integrated" answers fact 1 only; it never decides fact 2,
and an already-integrated project still gets the upload subgraph when a
variant matches. A compiled or bundled JS project normally has one: a Node
service built with `tsc` ships minified/compiled output, so it is the `node`
variant, not "none". Only two kinds of project skip the subgraph β€” the
readable-stack platforms listed above, and Astro.
**3. Which release-linking variant is this project β€” or none?** It applies
when the app itself is a server that runs Python, Ruby, or PHP source as is:

- a Python app (`requirements*.txt`, `pyproject.toml`, `Pipfile`, or
`setup.py`; Django, Flask, FastAPI, and plain Python alike) β†’ `python`
- a Ruby app (`Gemfile` or a `*.gemspec`; Rails, Sinatra, and plain Ruby
alike) β†’ `ruby`
- a PHP app (`composer.json`; Laravel and plain PHP alike) β†’ `php`
- **none** for every other platform. A manifest that only carries tooling for
another platform does not count: a `Gemfile` for CocoaPods or fastlane beside
a mobile app, or a `requirements.txt` for scripts beside a Node service. The
mobile uploader variants (`react-native`, `flutter`, `ios`, `android`) always
mean none here. Bundled and compiled platforms get their release from the
uploader, and Elixir, JVM servers, and .NET have no release-linking skill
yet.

When a variant matched, the skill id is
`error-tracking-link-releases-<variant>`. Pass it to `link-releases` as
`inputs: { skillId: "<id>", displayName: "<human platform name>" }`. Fact 3
does not depend on fact 2: a Django app that also bundles a Vite frontend in
the same project gets both the upload subgraph and `link-releases`, and both
default to the same release.

The three facts are independent β€” settle ALL of them before you enqueue
anything. "PostHog is already integrated" answers fact 1 only; it never decides
fact 2 or fact 3, and an already-integrated project still gets the upload
subgraph or `link-releases` when a variant matches. A compiled or bundled JS
project normally has an uploader variant: a Node service built with `tsc` ships
minified/compiled output, so it is the `node` variant, not "none". Only two
kinds of project skip the upload subgraph β€” the readable-stack platforms listed
above, and Astro.

Then seed the graph:

Expand All @@ -93,6 +120,11 @@ Then seed the graph:
- `configure`, after `capture-exceptions` β€” build-config changes; it runs
after the code edits so the two never fight over the same files.
- `wire-ci`, after `configure` and `credentials`.
- When a release-linking variant matched, `link-releases`, after
`capture-exceptions` β€” and after `wire-ci` too when you queued the upload
subgraph, because both edit the deploy pipeline. It changes production
deploys only, needs nothing from the user during the run, and leaves local
development as it is.
- `report`, after every other queued task except `test-setup`. It writes the
handoff once the work is done, so it describes what actually shipped.
- When you queued the upload subgraph, `test-setup` last, after `report` β€” it
Expand All @@ -110,10 +142,12 @@ Every task in the chosen graph is queued with that dependency shape, the four
upload tasks (when queued) share the same `{ skillId, displayName }` inputs,
`report` depends on every other task except `test-setup` (directly or
transitively), `test-setup` (when queued) depends on `report`, and the first
task is runnable. Your plan states both facts explicitly: whether PostHog was
integrated β€” and, when you called it integrated, the name of the key you found
defined β€” and which uploader variant matched β€” or, when you queue no upload
tasks, why no variant applies: which readable-stack platform this is, or that
Astro is not supported by the uploader. A
plan that never mentions fact 2 is an incomplete plan, not a decision. Keep
labels short β€” the action in a few words.
task is runnable. `link-releases` (when queued) carries its own
`{ skillId, displayName }` inputs. Your plan states all three facts explicitly:
whether PostHog was integrated β€” and, when you called it integrated, the name
of the key you found defined β€”, which uploader variant matched β€” or, when you
queue no upload tasks, why no variant applies: which readable-stack platform
this is, or that Astro is not supported by the uploader β€”, and which
release-linking variant matched, or that none applies. A plan that never
mentions fact 2 or fact 3 is an incomplete plan, not a decision. Keep labels
short β€” the action in a few words.
6 changes: 6 additions & 0 deletions context/marketplace.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,12 @@ plugins:
destination: skills/posthog/error-tracking-upload-source-maps
keywords: [posthog, error-tracking, source-maps, debugging]

error-tracking-link-releases:
name: posthog-error-tracking-link-releases
description: Skills for linking deploys to PostHog Error Tracking releases
destination: skills/posthog/error-tracking-link-releases
keywords: [posthog, error-tracking, releases, ci]

tools-and-features:
name: posthog-tools
description: Utility skills for working with PostHog (HogQL, etc.)
Expand Down
25 changes: 25 additions & 0 deletions context/skills/error-tracking-link-releases/config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Link releases skill β€” docs-only, one variant per server language that ships readable source
type: skill
template: description.md
description: Link each production deploy to a PostHog Error Tracking release for {display_name}
tags: [error-tracking, releases]
shared_docs:
- https://posthog.com/docs/error-tracking/releases.md
variants:
- id: python
display_name: Python
tags: [python]
docs_urls:
- https://posthog.com/docs/error-tracking/link-releases/python.md

- id: ruby
display_name: Ruby
tags: [ruby]
docs_urls:
- https://posthog.com/docs/error-tracking/link-releases/ruby.md

- id: php
display_name: PHP
tags: [php]
docs_urls:
- https://posthog.com/docs/error-tracking/link-releases/php.md
Loading
Loading