Documentation

Sign in, create a project, and install the GitHub App for only the repositories you choose. Personal access is an explicit fallback when the App is unavailable. Smart detect reads ninety days of shipping behaviour and recommends how this repository should drive the record — every recommendation shows its evidence and stays overridable.

Choose recent releases to import, review the drafts, then publish your first useful public page. Nothing in a history import is automatically published or emailed. Imports resume from saved checkpoints if the server restarts. Next, publish another release and check delivery status. Automatic publishing holds updates with missing evidence or failed source collection. Advisory uncertainty stays visible; your project policy controls additional review. Empty or internal-only maintenance stays in the record without an automatic customer announcement.

npm install -g logg-sh
logg login
logg project create --name "My app" --slug my-app --github me/my-app
logg sync --project my-app

A project is one changelog — usually one repository. An entry is one release, stored once as the complete truth: structured items grouped into breaking, features, improvements, fixes, and other. The markdown you see is rendered from those items by the server, never written twice.

Items carry two orthogonal ideas. Audiences say who a change matters to (users, developers, business). Visibility says how far it may travel — and that is what editions are made of.

An entry is written once; an edition is a rule over its items plus a way of presenting what it leaves out. public items appear as written. summarized items fold into one deliberately vague roll-up line per section — the outside world learns that something was done, never what. internal items never leave the team.

Two editions are built in: Customers (the page, the API, every feed) and Internal (everything, plus the evidence the writer worked from — Pro plans and up). Team plans add named custom editions with their own rules and access: public, members, or by secret link. One override outranks every rule: a disclosed vulnerability is forced public. Silence about a CVE is not an option.

Five ways a project can ship, one declaration:

Whatever the mode, a version bump in package.json, pyproject.toml, or Cargo.toml on the watched branch is a release boundary. Tagless modes assign versions by CalVer, a plain counter, or SemVer inferred from conventional commits — an inferred major bump flags itself for confirmation.

npm install @logg-sh/react

import { Changelog, ChangelogNotification } from "@logg-sh/react";
import "@logg-sh/react/styles.css";

<Changelog slug="my-app" maxEntries={10} tracking={false} />
<ChangelogNotification slug="my-app" position="bottom-right" tracking={false} />

The widget dresses in your site's clothes: every color reads your shadcn variables with dark fallbacks, overridable through --logg-*. Pass theme="logg" for the obsidian look, or renderEntry to take over rendering entirely. The hooks — useChangelog and useLatestChangelog — are exported for building your own.

Interaction reporting is off by default. Pass tracking={true} to each component to enable aggregate visible-release, bell-open and release-action events. Omitted or false values send no events. Do Not Track and Global Privacy Control suppress reporting even when enabled. The bell remembers seen releases independently.

The what's-new bell for any site, framework or none. It renders in a shadow root, follows the visitor's color scheme, remembers what they have seen, and removes itself if the project has nothing published.

<script src="https://logg.sh/widget.js" data-slug="my-app" data-position="bottom-right" data-tracking="false" defer></script>

Existing script tags keep reporting off. Only data-tracking="true" enables it, and Do Not Track or Global Privacy Control still suppress every event. Public releases are fetched and the bell remembers seen versions either way. Embed Studio generates snippets with an explicit, default-off reporting choice.

<iframe src="https://logg.sh/my-app/embed?tracking=false"
        width="100%" height="600" frameborder="0"></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.data?.type === "logg-sh-resize") {
      document.querySelector("iframe").height = event.data.height;
    }
  });
</script>

The iframe also defaults to no interaction reporting. Set ?tracking=true in its URL to opt in, or leave it omitted or false to keep reporting off. Do Not Track and Global Privacy Control still suppress events. Embed Studio updates both the snippet and preview link to match your reporting choice.

The embed allows any ancestor frame and reports its own height so the page never scrolls inside a box.

curl https://logg.sh/api/v1/changelogs/my-app
curl https://logg.sh/api/v1/changelogs/my-app/latest
curl "https://logg.sh/api/v1/changelogs/my-app?edition=internal" \
  -H "Authorization: Bearer <token>"

CORS-enabled reads, 60 requests a minute per caller. The default answer is the customers projection, publicly cached for a minute. Other editions authenticate (session or bearer) and never cache; refusals carry EDITION_AUTH, EDITION_PLAN, or EDITION_FORBIDDEN. Entries arrive with content (markdown) and categories (the structured items).

Every feed reads the same customers projection as the page — there is no side door an internal item could slip through.

Already keep a CHANGELOG.md? The overview's Import CHANGELOG.md reads the file straight from the repository and turns every version it declares into a draft entry by default — dates, categories and wording kept as written. Nothing is rewritten and nothing runs twice: versions already on the record are skipped. Review and publish the imported history when you are ready; importing does not notify subscribers.

The record can also flow the other way. The markdown feed is the whole published changelog as one document. Inspect or export it without overwriting a hand-maintained repository file:

curl -fsS https://logg.sh/my-app/changelog.md

For automatic repository updates on Pro or Team, connect the GitHub App and enable CHANGELOG file sync in project settings. It opens a pull request and changes only the section between <!-- logg:begin --> and <!-- logg:end -->. Content outside those markers stays intact; malformed markers stop the sync for review.

Point a CNAME at logg.sh, save the domain in project settings, and verify. Verification asks live DNS and, on failure, shows the records it actually observed. Once verified, the page, permalinks, and feeds all follow the domain. Paid plans.

Connect Linear at the organization level (read scope only) and switch it on per project. Completed issues inside a release window join the evidence — their descriptions usually explain the why better than any commit subject, and the writer is told to prefer them.

Connect Jira Cloud once per organization (Integrations → Jira), then switch on Jira issues in a project's sources — optionally narrowed to one project key. Issues resolved inside a release's window join its evidence next to the commits and pull requests. GitLab projects can do the same with issues closed in the window, no extra connection.

Both work as sign-in and as organization connections for repository access. Each project registers its own webhook with its own secret; detection modes work the same everywhere, with one nuance — Bitbucket has no release concept, so tags carry its history and imports read the newest ten.

Channels receive announcements on publish, and every channel is bound to an edition — #announcements can get the customer cut while #eng gets everything. A channel bound to an edition the plan no longer includes is skipped with the reason recorded, never silently downgraded.

Plain webhooks are signed: x-logg-signature is HMAC-SHA256 over timestamp.body with the secret shown once at creation, and every delivery carries a stable idempotency key so redeliveries dedupe.

const expected = "sha256=" + crypto
  .createHmac("sha256", secret)
  .update(`${req.headers["x-logg-timestamp"]}.${rawBody}`)
  .digest("hex");
const valid = timingSafeEqual(expected, req.headers["x-logg-signature"]);

Readers subscribe on the public page with double opt-in and leave with one click. Free includes 50 subscribers per project; Pro includes 500 and Team 2,000. Readers choose a public audience and individual updates or digest frequency; an expiring private link lets them change preferences or pause. Private editions cannot be selected for subscriber email. Imports cannot reverse an opt-out; resubscribing requires fresh confirmation. Existing global complaint/bounce blocks remain. Frequency and opt-outs are checked again before queued mail is sent.

Under Settings, tell the writer what the product does, who uses it, how you speak, and which names to keep (Pro). It still needs evidence for every claim; an example teaches style, never facts. When the writer fails or the month's allowance is spent, the release is not lost: its source record waits as a draft.

Every save is a revision. Publishing chooses a saved revision as the public copy, so editing a live entry never changes what readers see until you update it, and updating never resends email. Team can require a second person's approval of the exact revision, and invite reviewers and clients to one project without making them organization members.

Open Import from a project. Releases and tags come straight from the repository; a CHANGELOG.md keeps its wording, or lets the writer sort prose into sections. Markdown, JSON and CSV exports from another tool are previewed first and then imported as drafts with their original dates and links. Versions already on the record are skipped, and nothing imported is published or emailed. Subscriber lists need a consent date and source for every address; an opt-out is never reversed by an import.

Feeds and the Markdown or JSON exports carry the complete published history; page pagination is only for the page. The repository CHANGELOG.md sync replaces the logg-managed section and leaves the rest of the file alone.

Team can add up to five supporting GitHub repositories under a primary one. Match release tags across them, or read branch changes between release dates, which always wait for review. Path prefixes scope a monorepo to one product; mixed changes are held and flagged. Only the primary repository decides when a release happens.

Pro composes email from published releases: pick the releases, add an introduction, choose the audience and cadence, preview the saved copy, then send or schedule. The preview shows how many subscribers currently match; a change needs a fresh preview. Your name, logo, accent and footer come from the sender settings, and sending from your own address takes a DNS ownership record plus provider verification.

Scheduled digests wait for you unless automatic sending is on. The delivery log records what the provider said about each message: accepted means accepted, not opened. A held delivery is retried only after you confirm it did not arrive.

On Pro, each entry can carry upgrade notes: whether customers must act, the steps, and a documentation link. The public page builds a guide between any two published versions at /your-project/upgrade, collecting the breaking changes and steps on the way. Unknown compatibility is stated, never inferred, and only numeric or calendar versions can be compared.

GET /api/v1/changelogs/your-project/upgrade?from=1.0.0&to=2.0.0
# The MCP get_upgrade_guide tool provides the same public guide.

Pro gives each entry one action under it on the public page: try the feature, read the docs, start the migration. Insights counts page views, embed views, releases seen and action clicks as aggregate interactions, never unique people or profiles. Embedded reporting is off until you turn it on, and Do Not Track or Global Privacy Control switch collection off for that reader.

Optionally, your server can report a follow-through event with an authenticated project credential and a fresh event id. No user ids, emails or account data are accepted; retries with the same id are counted once for 30 days.

npm install -g logg-sh && logg login

logg project list · create
logg changelog list --project my-app
logg add · publish · unpublish --project my-app --version 1.4.0
logg sync · cut --project my-app
logg generate --project my-app --version 1.4.0
logg whoami · logout

Sign-in opens the browser and a confirmation page; the credential lands in ~/.config/logg with tight modes and lasts a year. Self-hosted? Set LOGG_API_URL.

claude mcp add --transport http logg https://logg.sh/api/mcp

Streamable HTTP at /api/mcp with OAuth 2.1 discovered automatically — your agent walks the consent flow itself, and you approve it on a consent screen once. The tools cover reading the record, upgrade guides, drafting from evidence, and publishing. The full table lives on the MCP page.