# Release Tracking

> Track releases, register deploys, and monitor crash-free session rates with the TraceKit CLI and REST API.

- Canonical: https://tracekit.dev/docs/frontend/releases

Track releases, register deployments, and monitor crash-free session rates. Identify regressions the moment they ship using the TraceKit CLI, REST API, or automatic detection from your SDK config.

## Quick Start

Install the TraceKit CLI, authenticate, and create your first release in under a minute.

### 1. Install the CLI

```bash
# Homebrew (macOS / Linux)
brew install tracekit-dev/tap/tracekit

# Direct download (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/Tracekit-Dev/cli/main/install.sh | sh
```

### 2. Authenticate

```bash
tracekit login
```

### 3. Create and deploy a release

```bash
# Create a release
tracekit releases new v1.0.0

# Register a deployment
tracekit releases deploy v1.0.0 --env production

# Mark the release as finalized
tracekit releases finalize v1.0.0
```

Or use the `deploy` shortcut to create, deploy, and finalize in one command:

```bash
tracekit releases deploy --env production
```

**Tip:** Releases are also auto-created when your browser SDK sends traces with a `release` (mapped to `service.version` in OTel resource attributes). No CLI needed for basic release tracking if you are already sending traces. See [Auto-Registration](#auto-registration) below.

## CLI Commands

All release commands are under `tracekit releases`. Every command supports a `--json` flag for machine-readable output in CI/CD pipelines.

### `releases new [version]`

Create a new release. If no version is provided, auto-detects from `package.json` version field, then falls back to the latest git tag. This command is idempotent: re-running with the same version silently succeeds.

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--commit` | string | Commit SHA. Defaults to auto-detect from git HEAD. |
| `--url` | string | Changelog or release URL. |
| `--author` | string | Release author name. |
| `--json` | boolean | Output JSON for CI/CD integration. |

```bash
# Create a release with explicit version
tracekit releases new v1.2.3

# Auto-detect version from package.json or git tag
tracekit releases new

# Create with metadata
tracekit releases new v1.2.3 --commit abc123 --url https://github.com/org/repo/releases/v1.2.3 --author "Dev Name"

# JSON output for CI
tracekit releases new v1.2.3 --json
```

### `releases finalize [version]`

Mark a release as finalized. This signals that the release is complete and fully deployed. If no version is provided, auto-detects from `package.json` or the latest git tag.

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--json` | boolean | Output JSON for CI/CD integration. |

```bash
# Finalize with explicit version
tracekit releases finalize v1.2.3

# Auto-detect version
tracekit releases finalize

# JSON output
tracekit releases finalize --json
```

### `releases deploy [version]`

Combined shortcut that creates a release, registers a deploy, and finalizes the release in one command. Each step is idempotent: if the release already exists, it continues to the deploy step. If no version is provided, auto-detects from `package.json` or the latest git tag.

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--env` | string | **Required.** Deployment environment (e.g., production, staging). |
| `--commit` | string | Commit SHA. Defaults to auto-detect from git HEAD. |
| `--url` | string | Changelog or release URL. |
| `--author` | string | Release author name. |
| `--deployer` | string | Name of the deployer or deploy system (e.g., deploy-bot, GitHub Actions). |
| `--json` | boolean | Output JSON for CI/CD integration. |

```bash
# Deploy to production (auto-detect version)
tracekit releases deploy --env production

# Deploy a specific version to staging
tracekit releases deploy v1.2.3 --env staging

# Deploy with deployer metadata
tracekit releases deploy --env production --deployer deploy-bot

# Full CI/CD usage with JSON output
tracekit releases deploy v1.2.3 --env production --commit abc123 --json
```

### `releases list`

List all releases with version, source, creation date, and finalization status. Supports pagination for large release histories.

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--page` | int | Page number. Default: 1. |
| `--page-size` | int | Number of releases per page. Default: 20. |
| `--json` | boolean | Output JSON for CI/CD integration. |

```bash
# List releases
tracekit releases list

# Paginated output
tracekit releases list --page 2 --page-size 10

# JSON output
tracekit releases list --json
```

**Example output**

```
Releases (page 1, 3 total):

  VERSION              SOURCE          CREATED              FINALIZED
  -------              ------          -------              ---------
  v1.2.3               cli             2025-03-15T10:30:00  2025-03-15T10:35:00
  v1.2.2               cli             2025-03-10T14:20:00  2025-03-10T14:22:00
  v1.2.1               auto-detected   2025-03-05T09:00:00  -

Environments: production, staging
```

## REST API Reference

All endpoints require an `X-API-Key` header with your organization API key. Base URL: `https://app.tracekit.dev`.

### POST /api/releases

Create a new release. Idempotent: creating the same version again returns the existing release.

**Request body**

```json
{
  "version": "v1.2.3",
  "commit_sha": "abc1234",
  "url": "https://github.com/org/repo/releases/v1.2.3",
  "author": "Dev Name"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | string | Yes | Release version identifier (e.g., v1.2.3). |
| `commit_sha` | string | No | Git commit SHA associated with this release. |
| `url` | string | No | Changelog or release notes URL. |
| `author` | string | No | Release author name. |

**Response 201 Created**

```json
{
  "id": "rel_abc123",
  "version": "v1.2.3",
  "commit_sha": "abc1234",
  "url": "https://github.com/org/repo/releases/v1.2.3",
  "author": "Dev Name",
  "source": "cli",
  "created_at": "2025-03-15T10:30:00Z",
  "finalized_at": null
}
```

### GET /api/releases

List all releases with pagination.

| Parameter | Type | Description |
| --- | --- | --- |
| `page` | int | Page number. Default: 1. |
| `page_size` | int | Items per page. Default: 20. |

**Response 200 OK**

```json
{
  "releases": [
    {
      "id": "rel_abc123",
      "version": "v1.2.3",
      "source": "cli",
      "created_at": "2025-03-15T10:30:00Z",
      "finalized_at": "2025-03-15T10:35:00Z"
    }
  ],
  "environments": ["production", "staging"],
  "total": 1,
  "page": 1
}
```

### GET /api/releases/:version

Get details for a specific release, including its deploy history.

**Response 200 OK**

```json
{
  "release": {
    "id": "rel_abc123",
    "version": "v1.2.3",
    "commit_sha": "abc1234",
    "url": "https://github.com/org/repo/releases/v1.2.3",
    "author": "Dev Name",
    "source": "cli",
    "created_at": "2025-03-15T10:30:00Z",
    "finalized_at": "2025-03-15T10:35:00Z"
  },
  "deploys": [
    {
      "id": "dep_xyz789",
      "environment": "production",
      "deployer": "deploy-bot",
      "deployed_at": "2025-03-15T10:32:00Z"
    }
  ]
}
```

### PATCH /api/releases/:version

Finalize a release. Sets `finalized_at` to the current timestamp.

**Response 200 OK**

```json
{
  "id": "rel_abc123",
  "version": "v1.2.3",
  "source": "cli",
  "created_at": "2025-03-15T10:30:00Z",
  "finalized_at": "2025-03-15T10:35:00Z"
}
```

### POST /api/releases/:version/deploys

Register a deployment for an existing release.

**Request body**

```json
{
  "environment": "production",
  "deployer": "deploy-bot"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string | Yes | Deployment environment (e.g., production, staging). |
| `deployer` | string | No | Name of the deployer or deploy system. |

**Response 201 Created**

```json
{
  "id": "dep_xyz789",
  "environment": "production",
  "deployer": "deploy-bot",
  "deployed_at": "2025-03-15T10:32:00Z"
}
```

### GET /api/releases/:version/health

Get health metrics for a release, including crash-free rate, issue counts, and trend data.

**Response 200 OK**

```json
{
  "crash_free_rate": 99.2,
  "total_sessions": 15420,
  "crashed_sessions": 123,
  "crash_free_history": [
    { "date": "2025-03-15", "rate": 99.5 },
    { "date": "2025-03-16", "rate": 99.1 },
    { "date": "2025-03-17", "rate": 99.2 }
  ],
  "new_issue_count": 3,
  "regressed_issue_count": 1
}
```

## Auto-Registration

Releases are automatically created when your browser SDK sends traces that include a `release` value. The SDK maps `release` to `service.version` in the OpenTelemetry resource attributes. When the server receives a span with a `service.version` that does not match an existing release, it automatically creates one.

```ts
import { init } from '@tracekit/browser';

init({
  apiKey: 'your-api-key',
  release: '1.0.0',  // This version is auto-registered as a release
});
```

### How it works

1. Your SDK sends traces with `service.version` set to your release value.
2. The TraceKit server checks if a release with that version already exists.
3. If not, it creates a new release with `source: "auto-detected"`.
4. Errors and sessions are associated with this release for health tracking.

Auto-registered releases are tagged as `auto-detected`, while CLI-created releases are tagged as `cli`. Auto-registration does not include commit SHA, URL, or author metadata. For richer release data, use the CLI or REST API to create releases explicitly in your CI/CD pipeline.

## Dashboard

The release dashboard is available at `/releases` in the TraceKit app sidebar. It provides a real-time view of your release health.

- **Release list** -- Version, source (cli or auto-detected), creation date, and finalization status at a glance.
- **Crash-free session rate** -- Per-release percentage with a sparkline trend chart showing rate over time. Green when healthy, red when degraded.
- **Issue counts** -- Number of new issues and regressed issues introduced by each release. Helps identify which release caused a regression.
- **Environment filter** -- Filter releases by deployment environment (production, staging, etc.) to focus on the environments that matter.

**Tip:** The crash-free rate sparkline renders as a 60x20px SVG polyline. A dot on the latest data point shows the current rate, and the line color indicates the trend (green = stable/improving, red = degrading).

## Troubleshooting

### CLI authentication errors

If you see `not authenticated. Run 'tracekit login' first`, your CLI session has expired or was never created.

```bash
# Re-authenticate
tracekit login

# Verify authentication
tracekit status
```

### Version auto-detection not working

The CLI tries to detect the version from `package.json` in the current directory first, then falls back to the latest git tag. If neither is found, pass the version explicitly.

```bash
# Check that package.json exists and has a "version" field
cat package.json | grep version

# Or check for git tags
git tag --list

# Provide version explicitly as a fallback
tracekit releases new v1.2.3
```

### Releases not appearing in dashboard

If releases created via the CLI are not showing in the dashboard, verify that your API key has the correct scope and belongs to the same organization.

```bash
# Verify your releases exist via CLI
tracekit releases list --json

# Check that the API key matches your organization
tracekit status
```