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. 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/?slug=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.

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/?slug=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

- name: Submit release notes
  env:
    RELEASE_COMPASS_API_KEY: ${{ secrets.RELEASE_COMPASS_API_KEY }}
    API_URL: https://api.release-compass.app
    PAYLOAD: |
      {
        "version": "${{ github.ref_name }}",
        "title": ${{ toJson(github.event.release.name) }},
        "body": ${{ toJson(github.event.release.body) }},
        "url": "${{ github.event.release.html_url }}"
      }
  run: |
    curl -sS -X POST "$API_URL/api/v1/releases" \
      -H "Authorization: Bearer $RELEASE_COMPASS_API_KEY" \
      -H "Idempotency-Key: ${{ github.run_id }}" \
      -H "Content-Type: application/json" \
      -d "$PAYLOAD"

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 POST /api/v1/mcp with the same Bearer API key. create_release opens a draft. Handshake (initialize, tools/list) does not count against the monthly quota; tool calls do. Publishing stays in the dashboard.

{
  "mcpServers": {
    "release-compass": {
      "url": "http://localhost:3001/api/v1/mcp",
      "headers": { "Authorization": "Bearer rc_live_…" }
    }
  }
}

create_release arguments: version, title, body, optional url, channel, locale, and changes. Also available: list_releases, get_release.

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.

• Save with JWT PATCH /api/v1/releases/:id (customerTitle, customerBody, customerChanges, optional locale). Markdown patches are also accepted.
• 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/?slug=your-project. 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.