Chart notes and GitHub

Use Analytics → Notes to place campaigns, releases and other changes beside traffic. Every note belongs to one application environment. Manual notes can be edited or removed; imported notes can be hidden and restored.

Add a note

Choose Add note, select a category and enter a date, title and optional context or related link. Dates use the application timezone. During a repeated daylight-saving hour, the console selects the earlier occurrence; the Management API accepts an explicit offset for either occurrence. Nonexistent local times are rejected.

The overview groups nearby notes into up to six numbered markers, with an accessible dated list below the chart. Open Notes for the complete, paginated history and category filters. Chart context applies to the entire environment, including when audience filters are active. Temporal proximity does not establish causation.

Connect GitHub

1. Open Notes → GitHub integrations → Connect a GitHub repository.
2. Enter owner/repository, the push branch and GitHub deployment environment. The current console environment receives the notes.
3. Save, then copy the one-time signing secret and payload URL.
4. In the GitHub repository, open Settings → Webhooks → Add webhook. Paste the URL and secret; choose application/json, keep SSL verification enabled and select Pushes and Deployment statuses.
5. Send the initial ping. Refresh Notes to see Verified GitHub ping. A matching branch push or successful deployment status creates a note.

https://your-console.example/api/v1/webhooks/github-annotations/SOURCE_ID

The console must be publicly reachable over HTTPS for GitHub delivery. No GitHub access token is needed. Creating, editing, rotating or removing an integration in the console requires a passkey verified within ten minutes.

Push notes record webhook receipt time and the latest pushed commit. They are not deployment proof. Branch deletion and other branches are ignored. Deployment notes require a successful status in the configured GitHub environment and use its reported status timestamp. A status-level environment takes precedence when GitHub changes the deployment target. GitHub Actions must actually publish deployment statuses for these notes to appear.

Private commit summaries are visible to application members with analytics read access. Do not include secrets or personal data in commit messages or manual notes.

Delivery and retention

Raw-body SHA-256 HMAC signatures and the exact repository are checked before writing. Duplicate delivery IDs, signed body replays and repeated commit/deployment identifiers do not create duplicate notes. Reusing a delivery ID for different content returns a conflict. Deliveries are limited to 1 MB; push and deployment timestamps must be no more than seven days old and no more than five minutes ahead. Older deliveries are ignored; use a manual note for historical context.

Pause an integration to ignore new deliveries. Rotate its secret if needed, then immediately update GitHub: the old secret stops working. Removal deletes that integration’s imported notes and revokes its local secret. Remove the GitHub webhook too. These actions preserve manual notes.

Each application supports eight GitHub integrations. Each environment supports 5,000 manual notes. Each integration supports 50,000 imported notes and 50,000 delivery receipts. Hourly cleanup retains imported notes for the application's retention period, capped at 365 days, and delivery receipts for 90 days. Manual notes remain until removed.

Management API

Use a Management API token with analytics read/write permission. Public ingest keys cannot list or change notes. All endpoints honor ?env= and check application access; writes are audited.

{
  "kind": "release",
  "title": "Pricing page launch",
  "body": "New annual plan is available.",
  "occurredAt": "2026-09-07T10:00:00+09:00",
  "url": "https://example.com/changelog"
}

Updates include the current revision; stale revisions return a conflict. Visibility changes use {"revision":1,"hidden":true}. Delete, rotate and remove use {"revision":1}. List ranges are exclusive at to, limited to 366 days and default to the preceding 30 days. The console setup does not backfill GitHub history.

GitHub references: webhook signatures, event payloads.