How to generate a release

The path

1. Create a project in the dashboard. The owner is admin. On the free plan, invited members join as release managers and can write and publish.
2. Open a draft — type it in the dashboard, or POST JSON or Markdown with a project API key, or call MCP create_release. Dashboard creates do not count toward the monthly API quota; API-key and MCP tool calls do.
3. Source title, body, and changes are copied to the customer-facing fields, then frozen. Optionally let AI customer copy rewrite the draft (bring your own key). Edit the customer copy, including extra languages.
4. Publish once. The hosted changelog, RSS, Atom, and confirmed subscriber email update together. Publishing is idempotent: people who already received the note are not emailed again.

Write it in the dashboard

You do not need GitHub, Jira, or an API key to ship the first note. Open Dashboard, pick the project, and create a draft:

• Version — for example v1.4.0. Unique per project.
• Title — short customer headline.
• Channel — stable, rc, beta, alpha, or canary. Defaults to stable.
• Body — Markdown. An intro paragraph plus headed lists (Features, Bug fixes, Chore) is enough.

JWT POST /api/v1/projects/:projectId/releases is the same create, used by the dashboard. Admins and release managers can call it.

Structure the notes

Headings such as Features, Bug fixes, and Chore, followed by list items, become grouped change lists on the public changelog. You can also edit those lists in the dashboard. Optional detail after an em dash becomes a description:

Customers can export invoices.

## Features
- Billing export — CSV for finance
- Audit log

## Bug fixes
- Expired tokens

## Chore
- Bump dependencies

Recognised headings include Features, Added, Bug fixes, Fixes, Improvements, Breaking, Chore, and Maintenance. JSON can send the same structure as changes: [{ type, title, description? }]. Types: feature, fix, improvement, breaking, chore, other.

Channels and languages

Each release has one channel. The public page shows stable by default; readers can include pre-releases. Email subscribers pick the channels they want.

• stable — production
• rc — release candidate
• beta — feature-complete preview
• alpha — early experimental
• canary — nightly / bleeding-edge

The project has a default locale (BCP 47, usually en). Extra languages are translations of the customer title, body, and change lists. Readers use ?lang= on the changelog; missing copy falls back to the default.

Open a draft from the API

Create an API key in the dashboard (admin or developer). POST to /api/v1/releases with Authorization: Bearer rc_live_…. The parser follows Content-Type.

curl -sS -X POST "$API_URL/api/v1/releases" \
  -H "Authorization: Bearer $RELEASE_COMPASS_API_KEY" \
  -H "Idempotency-Key: $CI_JOB_ID-$VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1.4.0",
    "title": "Billing export",
    "body": "Finance can download invoices as CSV.",
    "url": "https://release-compass.app/changelog/acme/your-project/",
    "channel": "stable",
    "locale": "en",
    "changes": [
      { "type": "feature", "title": "CSV export", "description": "Invoices for finance." }
    ]
  }'

Idempotency-Key is optional. Retrying the same key does not create a second draft. Unsupported content types return 415. The project comes from the API key; the JSON response includes slug, changelogUrl (/changelog/acme/your-project/v1.4.0/), and editorUrl for the dashboard editor (/dashboard/acme/projects/your-project/releases/…/). Name API keys in the dashboard (GitHub Action token, MCP token, and so on). Keys created without a name show as default.

Import an existing changelog with POST /api/v1/releases/bulk { "releases": [ { "version", "title", "body", "publishedAt?" } ] } (1–50 items). Each item is published. Optional publishedAt may be a past ISO-8601 instant so historical notes keep their original dates; omit it to use now. Single POST /api/v1/releases still opens a draft and does not accept publishedAt. That path is API and MCP only for now.

Open a draft from Markdown

POST a changelog excerpt or GitHub release body as text/markdown or text/x-markdown. Version comes from X-Release-Version or YAML front matter. Title from X-Release-Title, front matter title, or the first # heading. Channel and locale from headers or front matter. ## Features / ## Bug fixes lists become structured changes.

curl -sS -X POST "$API_URL/api/v1/releases" \
  -H "Authorization: Bearer $RELEASE_COMPASS_API_KEY" \
  -H "Content-Type: text/markdown" \
  -H "X-Release-Version: v1.8.0" \
  -H "X-Release-Url: https://release-compass.app/changelog/acme/your-project/" \
  --data-binary @- <<'MD'
---
title: SSO and audit log
channel: stable
---

Customers can sign in with their company IdP.

## Features
- SAML SSO
- Audit log

## Bug fixes
- Expired invite links
MD

GitHub Actions and CI

Any job that can POST HTTP can open a draft: GitHub Actions, GitLab CI, Jira automation, Linear, or a script. Store the project API key as a secret. Only the JSON or Markdown you include is sent.

GitHub Actions

Pin the public action tech-trail-io/release-compass-action to @v0. Pass title and body as inputs so GitHub keeps newlines.

- uses: tech-trail-io/release-compass-action@v0
  with:
    token: ${{ secrets.RELEASE_COMPASS_TOKEN }}
    version: ${{ github.ref_name }}
    title: ${{ github.event.release.name }}
    body: ${{ github.event.release.body }}
    url: ${{ github.event.release.html_url }}
    idempotency-key: ${{ github.run_id }}

GitLab CI

submit_notes:
  image: alpine:3.20
  script:
    - apk add --no-cache curl jq
    - |
      jq -n \
        --arg version "$CI_COMMIT_TAG" \
        --arg title "$CI_COMMIT_TAG" \
        --arg body "$CI_COMMIT_MESSAGE" \
        '{version:$version,title:$title,body:$body}' \
      | curl -sS -X POST "$API_URL/api/v1/releases" \
          -H "Authorization: Bearer $RELEASE_COMPASS_API_KEY" \
          -H "Idempotency-Key: $CI_PIPELINE_ID" \
          -H "Content-Type: application/json" \
          -d @-

Jira, Linear, or a webhook worker is the same POST. We are not a GitHub App and not a Jira marketplace app.

MCP

Point an MCP client at https://api.release-compass.app/api/v1/mcp with the same Bearer API key. create_release opens a draft. create_releases imports published historical notes (optional past publishedAt). update_release edits unpublished customer copy. put_release_translation adds a language on a draft or published note. publish_release publishes now; schedule_release holds a future note; unpublish_release pulls a note back to draft. delete_release permanently removes a note. Handshake (initialize, tools/list) does not count against the monthly quota; tool calls do.

{
  "mcpServers": {
    "release-compass": {
      "url": "https://api.release-compass.app/api/v1/mcp",
      "headers": { "Authorization": "Bearer rc_live_…" }
    }
  }
}

create_release arguments: version, title, body, optional url, channel, locale, and changes. Also available: get_project, list_releases, get_release, create_releases, update_release, rewrite_release_customer_copy, put_release_translation, publish_release, schedule_release, unpublish_release, delete_release, approve_request.

Agent skills

The plugin tech-trail-io/release-compass-skills rewrites GitHub-shaped changelogs into customer-facing copy and calls MCP for you: list existing notes, import history with original dates, add languages, then publish. It does not clone your repo. The plugin MCP URL is the same Streamable HTTP endpoint as above. The same repository installs in Cursor and Claude Code.

Cursor

1. In Cursor, open Customize and import the GitHub repository as a team marketplace.
2. Install release-compass-skills.
3. Set the project API key (rc_live_…) when prompted. Create it in the dashboard and name it, for example, MCP.

Claude Code

/plugin marketplace add tech-trail-io/release-compass-skills
/plugin install release-compass-skills@release-compass-skills

Set the project API key when prompted. Skills are namespaced, for example /release-compass-skills:customer-facing-changelog. Reload with /reload-plugins if MCP tools do not appear.

Skills cover customer-facing rewrite, historical import (create_releases), which MCP tool to call, and translations. You can copy the skill files into .cursor/skills/ or .claude/skills/ instead of installing the plugin; you still configure MCP yourself. Claude Desktop and claude.ai have no plugin marketplace: add a custom connector to the MCP URL with a Bearer API key.

AI customer copy

Available on Pro and Team. Turn frozen technical source notes into a customer-facing draft with your own OpenAI-compatible API key. AI never publishes — a release manager still reviews and publishes. This is separate from the project rc_live_… key used for CI and MCP.

1. Create or open the project in the dashboard. You need the admin role.
2. Open Integrations for that project.
3. Get an API key from your OpenAI-compatible provider (OpenAI platform → API keys, or your Azure / proxy console). Copy it once — Release Compass will not show it again after save.
4. Paste the key into the AI API key field. Optionally set Base URL (default https://api.openai.com/v1) and Model (default gpt-4o-mini).
5. Select the Languages AI should write. The project default is always included; optional extras (Hungarian, German, and so on) are stored as translations on the draft.
6. Turn on Auto-rewrite on new drafts if CI or MCP creates should rewrite immediately. Leave it off to only use the dashboard Rewrite with AI button, POST /api/v1/releases/:id/ai-rewrite, or MCP rewrite_release_customer_copy.
7. Save. Confirm the UI shows the key as configured (not the secret itself).
8. Open a draft (or trigger rewrite). Review each language of the customer title and body, edit if needed, then publish.

Project API keys for REST and MCP are still created under API keys (rc_live_…). They authorize create and rewrite calls; they are not the LLM key. Pass skipAiRewrite: true on create when the payload is already customer-ready.

Company SSO

Available on the Team plan. Creating an organization starts a 30-day Team trial with no card. Configure OIDC or SAML under Dashboard → Organizations → SSO. Allowed email domains discover the organization on the login page so people can Continue with company SSO. GitHub, Google, and Microsoft buttons on sign-in are personal social login — they are not your company IdP.

1. Create an organization (starts the Team trial).
2. Open SSO and choose OIDC or SAML.
3. Enter issuer / client credentials (OIDC) or entity id, SSO URL, and certificate (SAML). Add allowed email domains.
4. Optionally enable JIT provisioning and block password sign-in for those domains.
5. Transfer or create a project under the organization when you want org-owned ownership.

Edit, then publish

Open the draft in the dashboard. Source content is read-only. Customer-facing title, Markdown body, and change lists are editable. Add a language from the locale switcher if you ship more than one market. If you configured AI customer copy, use Rewrite with AI for a first draft, then edit before publish.

• Save with JWT PATCH /api/v1/releases/:id (customerTitle, customerBody, customerChanges, optional locale), or MCP update_release on drafts and scheduled notes. Add a language with JWT PUT /api/v1/releases/:id/locales/:locale or MCP put_release_translation even after the note is published. Markdown patches are also accepted on the REST PATCH path. Published default-language corrections set editedAt and show Edited on the changelog. It does not email subscribers again.
• Publish with JWT POST /api/v1/releases/:id/publish. The response includes how many emails were sent, failed, or skipped.

{
  "release": { "status": "PUBLISHED" },
  "notifications": { "attempted": 2, "sent": 1, "failed": 0, "skipped": 1 }
}

What readers get

After publish, share https://release-compass.app/changelog/acme/your-project/. Each published version also has its own page at /changelog/acme/your-project/v1.4.0/. Readers can switch language, include pre-releases, subscribe to email by channel, or follow RSS and Atom. JSON lives at GET /api/v1/public/changelogs/:slug.

OpenAPI is at https://api.release-compass.app/api/docs. Agents can also read llms.txt.

Embed in your product

Client libraries live in tech-trail-io/release-compass-clients. Public embeds call the public API with your project slug — no API key in the browser. Private request boards and voting use a project API key on your backend only.

• @techtrail/release-compass-react — public Changelog and RequestBoard
• @techtrail/release-compass-angular — rc-changelog and rc-request-board
• @techtrail/release-compass-next — server helpers that read RELEASE_COMPASS_API_KEY (never NEXT_PUBLIC_*)
• @techtrail/release-compass-core — createPublicClient and createServerClient
• @techtrail/release-compass-vue — Soon

import {
  ReleaseCompassProvider,
  Changelog,
  RequestBoard,
} from "@techtrail/release-compass-react";

export function ProductUpdates() {
  return (
    <ReleaseCompassProvider projectSlug="your-project-slug">
      <Changelog />
      <RequestBoard />
    </ReleaseCompassProvider>
  );
}

For an upvote from a Next.js Route Handler:

import { voteRequest } from "@techtrail/release-compass-next";

export async function POST(
  request: Request,
  context: { params: Promise<{ id: string }> },
) {
  const { id } = await context.params;
  const { voter } = (await request.json()) as { voter: string };
  return Response.json(await voteRequest(id, voter));
}

Agents can follow the release-compass-embed-clients skill in the skills plugin to wire these packages into an app.