Mark every GitHub release on your Amplitude charts

Whenever a GitHub release is published, mirror it into Amplitude so every deploy shows up as a vertical marker on our funnel, retention, and segmentation charts. This is a deterministic passthrough — no reasoning, no summarization, just field mapping.

Trigger: GitHub webhook on the release event, filtered to action=published. Read the release tag, release title, release body, and the published_at timestamp off the payload.

Before the first annotation is ever created, ensure the 'Releases' annotation category exists in Amplitude. Call Amplitude's List Annotation Categories and look for a category named 'Releases'. If it isn't there, call Amplitude's Create Annotation Category with name='Releases' once. Cache the resulting category id for subsequent runs so we don't re-check every time.

Then, for each published release, do two things in Amplitude:

1. Call Amplitude's Create Chart Annotation. Use the release tag as the annotation label, the release body (release notes) as the description, and the 'Releases' category id from the step above. The date must be formatted as YYYY-MM-DD — convert the GitHub published_at timestamp to that format in the project's timezone.

2. Call Amplitude's Create Release with the release tag as the version, the release title as the release name, the release body as the description, and the same YYYY-MM-DD release date. This is what makes future funnel and retention charts render the deploy as a vertical marker automatically.

Expose a repository/branch filter as a customizable knob (default: fire on every release from the connected repo). A common setup is to only annotate releases whose tag matches a prod pattern (e.g. starts with 'v' and is a semver tag on the default branch), so pre-releases and hotfix drafts don't clutter the charts. Skip GitHub releases where prerelease=true or draft=true by default; make that toggleable.

Reference: Amplitude documents this pattern in their Releases doc at https://amplitude.com/docs/analytics/releases. Amplitude annotation dates are strictly YYYY-MM-DD; do not pass ISO timestamps. The annotation category is a one-time setup — never create it more than once, always check first.