deployment-tracker

# deployment-tracker Skill

## When to Use

Use this skill when you need to:
- Log deployments from a CI/CD pipeline to a central tracker
- View a history of who deployed what version to which environment
- Track rollback events and mean time to recovery
- Manage per-service deploy tokens for CI/CD pipelines
- Query deployment history by service, environment, or status

## Prerequisites

- Node.js 20+
- pnpm 9+
- `ADMIN_TOKEN` environment variable set (a secure random string)

## Quick Start

```bash
cd deployment-tracker
cp .env.example .env
# edit .env: set ADMIN_TOKEN=<secure random string>

pnpm install
pnpm --filter server dev    # API on :4000
pnpm --filter client dev    # dashboard on :5173
```

## Docker Quick Start

```bash
ADMIN_TOKEN=mysecrettoken docker compose up
# API: http://localhost:4000
# Dashboard: http://localhost:3000
```

## Logging Deployments via CLI

### Install

```bash
npm install -g deploy-tracker
```

### Log a deployment

```bash
deploy-tracker deploy \
  --service api-gateway \
  --version v2.4.1 \
  --env production \
  --deployer alice \
  --token $DEPLOY_TOKEN \
  --changelog-url https://github.com/acme/api-gateway/releases/tag/v2.4.1 \
  --notes "Hotfix for auth timeout"
```

### Log a rollback

```bash
deploy-tracker rollback \
  --deployment dep_9xK3mNpQvLrTwY \
  --reason "increased error rate on payment endpoint" \
  --token $DEPLOY_TOKEN
```

### List recent deployments

```bash
deploy-tracker list \
  --service api-gateway \
  --env production \
  --limit 10 \
  --admin-token $ADMIN_TOKEN
```

## Logging Deployments via API

```bash
curl -X POST http://localhost:4000/api/deploy \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "api-gateway",
    "version": "v2.4.1",
    "environment": "production",
    "deployer": "alice",
    "status": "success",
    "changelog_url": "https://github.com/acme/api-gateway/releases/tag/v2.4.1"
  }'
```

## Querying the Timeline

```bash
# List all deployments
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:4000/api/deployments

# Filter by service and environment
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://localhost:4000/api/deployments?service=api-gateway&environment=production"

# Filter by status
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://localhost:4000/api/deployments?status=rolled_back"

# Single deployment detail
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:4000/api/deployments/dep_9xK3mNpQvLrTwY
```

## Managing Deploy Tokens

### Create a token

```bash
curl -X POST http://localhost:4000/api/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_id": "svc_abc", "label": "GitHub Actions"}'
# Returns: {"token": "dt_raw_token_value_shown_once", "id": "tok_xyz"}
```

The raw token is shown once. Store it as a CI secret immediately.

### Revoke a token

```bash
curl -X DELETE http://localhost:4000/api/tokens/tok_xyz \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `4000` | Server listen port |
| `DB_PATH` | `./data/tracker.db` | SQLite database path |
| `ADMIN_TOKEN` | (required) | Bearer token for admin API access |
| `CORS_ORIGIN` | `http://localhost:5173` | Dashboard origin for CORS |
| `DEPLOY_TRACKER_URL` | `http://localhost:4000` | Server URL used by CLI |

## Stats Endpoint

```bash
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:4000/api/stats
```

Returns: `deployments_today`, `failed_today`, `rollback_rate`, `active_services`, `deployments_by_service`.