GamebeastDocs
Dashboard

Annotations

Mark releases, live events, incidents and experiment changes on every time chart in your project, so you can see what changed when a metric moves.

Annotations mark moments and periods on every time chart in your project. Use them for a release, a live event, a sale, an outage, or anything else that might explain why a metric moved. Each annotation is either a point (a single moment) or a range (a start and an end).

Annotations belong to the project, not to one chart: add one and it shows on every time chart, dashboard and query in that project. They follow the environment switcher, so production and development annotations stay separate.

Experiments are annotated for you. When an experiment starts, Gamebeast adds a range for it, and each rollout change (paused, resumed, percentage changed) adds a point.

Types

Every annotation has a type, such as Releases, Live events or Incidents. A type sets the icon and color the annotation is drawn with, and lets charts show or hide a whole group at once.

  • Types are defined per project. Create them from the Annotations tab or straight from a chart while adding an annotation.
  • Each type has a name, an optional description, an icon, a color, and whether charts show it by default.
  • Archive a type to hide it from charts and pickers without losing its annotations. Restore it any time. A type with no annotations can be deleted.
  • Gamebeast's own types, Experiments and Experiment rollouts, are marked with a lock. You can change their color and whether they show by default, but not rename them, archive them or add annotations to them by hand. Experiment rollouts are hidden by default.

Adding an annotation

From a chart. Under every time chart is a thin strip where annotations sit.

  • Click the strip to add a point at that time.
  • Drag along the strip to add a range.
  • Or select + beside the filter button at the left of the strip.

A small form opens with the type, name and time filled in. Add a description or link if you like, then save.

From the Annotations tab. Open Data > Annotations and choose New annotation. This is also where you see every annotation in a searchable table, filter by type or by who added it, and edit or delete any of them.

Anyone who can edit annotations can change or delete any custom annotation, not only their own. Annotations Gamebeast wrote for experiments are read-only: change the experiment instead.

Reading annotations on a chart

  • Points show as chips on the strip. Hover one to see its name, time, description, who added it and its link. Nearby points are grouped so they stay readable.
  • Ranges show as labelled bars. When several ranges overlap, they fold into a compact track; hover it to see every range at that moment.
  • A range that is still running (an experiment with no end date, for example) extends to now.
  • Use the filter button at the left of the strip to choose which types a board shows. The choice is saved per board in your browser.

Annotations are off on share links until you turn them on. When creating or editing a share link, select Show annotations and pick which types the link includes. Viewers see those annotations on the shared charts, without the names of the people who added them.

Sources: annotations from GitHub and CI

A source is a webhook URL that turns events from another tool into annotations, so releases and deploys appear on your charts without anyone adding them by hand. Each source writes one annotation type, in the environment it was created in.

Open Data > Annotations, then choose New source under Sources. Pick GitHub or Generic JSON, pick the type to write, and choose Get the webhook URL.

The URL is the credential: anyone with it can add annotations. Keep it in your CI's secret store, not in a public repository. If it leaks, delete the source and create a new one.

GitHub

In your repository, open Settings > Webhooks > Add webhook and fill in:

GitHub fieldValue
Payload URLThe source's URL
Content typeapplication/json
SecretThe secret Gamebeast shows when you create the source (shown once)
EventsLet me select individual events, then Releases and Deployment statuses

GitHub sends a test ping when you save, and the source shows it arrived. After that:

  • A published release becomes a point named Release v1.45.0, linked to the release.
  • A successful deployment becomes a point named Deployed main to production, linked to its log.
  • Pushes, drafts, failed deployments and other events are received but not annotated.

Every request is checked against the secret. If you lose it, choose Rotate secret on the source; the old secret stops working at once.

Generic JSON

Send a POST with a JSON body to the source's URL. A body that uses these field names works with no setup:

FieldMeaning
nameThe label on the chart (required)
descriptionOptional text
startsAtWhen it happened: ISO 8601, or epoch seconds or milliseconds. Defaults to when it arrived
endsAtMakes it a range
urlAn https link
idempotencyKeyAny string; sending the same key again does not add a second annotation
curl -X POST "$GAMEBEAST_ANNOTATIONS_URL" \
  -H "content-type: application/json" \
  -d '{"name":"Winter sale","startsAt":"2026-12-01T00:00:00Z","endsAt":"2026-12-08T00:00:00Z"}'

To annotate each deploy from GitHub Actions, store the URL as a repository secret and add a step:

- name: Annotate deploy
  run: |
    curl -sf -X POST "${{ secrets.GAMEBEAST_ANNOTATIONS_URL }}" \
      -H "content-type: application/json" \
      -d "{\"name\":\"Deploy ${GITHUB_SHA::7}\",\"idempotencyKey\":\"${{ github.run_id }}\"}"

You can also require a secret: turn on Require a secret when creating the source (or choose Add secret later), then send it in the x-gamebeast-secret header.

Mapping other payloads

If your tool sends its own format, map it. Once the first event arrives, the source shows what it becomes. Choose Customize mapping to set each field to a template, such as Deploy {{deploy.version}}, where {{...}} is a path into the payload. The field picker lists every field in the last payload, and the preview updates as you type.

Only when lets one source ignore some events: status == finished annotates only payloads whose status is finished. Use != for the opposite.

Deliveries

Each source keeps its last 20 deliveries, with what happened to each:

StatusMeaning
CreatedAn annotation was added
Already addedThe same event arrived again (same idempotency key); nothing new was added
ReceivedThe payload was stored but not annotated: GitHub's test ping, or no mapping yet
SkippedNot annotated: an event this source ignores, a failed Only when test, or no name
RejectedThe signature or secret didn't match, or the body wasn't JSON
FailedThe source's settings are wrong, for example its type was archived

Gamebeast answers every accepted request with 200, including skipped ones, so tools don't retry forever. A bad signature or secret gets 401. Turning a source off keeps its URL but stops it adding annotations. Deleting a source keeps the annotations it already added.

From the assistant and MCP

The assistant and MCP clients can read and write annotations:

ToolUse it for
list_annotationsFind what happened around a date: releases, events, incidents
list_annotation_typesSee the project's types
create_annotationAdd a point or range
update_annotationChange one
delete_annotationRemove one
create_annotation_typeAdd a type

When the assistant explains a change in a metric, it looks at the annotations in that window, so "why did retention drop last week?" can point at the release that shipped that day. In the assistant, every write asks for your approval first. Annotations it adds show Assistant or MCP as their source.

API

Annotations are available from the API with a personal access token:

  • GET /application/{applicationId}/analytics/v1/annotations lists annotations, newest first. Pass from and to for the ones overlapping a window, and filter by type, source or text.
  • POST, PATCH and DELETE on the same path add, change and remove them. Send an idempotencyKey when creating from a script so a retry doesn't add a duplicate.
  • /annotations/types lists and manages types.

Every request takes an environment-id header. See the API reference for every parameter. Sources can only be managed from the dashboard.

Who can do what

PermissionAllowsBuilt-in roles
annotations:readSeeing annotations on charts, the Annotations tabViewer and above
annotations:writeAdding, editing and deleting annotations, types and sourcesEditor and above

Grant either to custom roles in Settings > Roles. Every change to an annotation, type or source is recorded in the audit log.

On this page