Publish a changelog entry from your agent

• A connected MCP client with changelog:read and changelog:write.
• status:write as well, if the project's public pages are not published yet.

Use a stable external_id, such as a release name. Front matter sets the title, and optionally the summary, area and version.

{
  "name": "actions.write",
  "arguments": {
    "action": "changelog.upsert_draft",
    "idempotency_key": "release-2026-09-15-draft",
    "arguments": {
      "external_id": "release-2026-09-15",
      "markdown": "---\ntitle: Heartbeat exit codes\nsummary: Report a job result from its exit code.\narea: monitor\n---\n\nAdd `/h/TOKEN/$?` to the end of a crontab line.\n",
      "sources": [{ "kind": "issue", "url": "https://github.com/example/app/issues/42", "label": "#42" }]
    }
  }
}

Send changelog.upsert_draft again with the same external_id to update the draft in place. Read the rendered result with changelog.preview_entry, and the history with changelog.list_revisions.

Pass the revision you reviewed. Publishing happens at once and needs no dashboard approval.

{
  "name": "actions.publish",
  "arguments": {
    "action": "changelog.publish_entry",
    "idempotency_key": "release-2026-09-15-publish",
    "arguments": { "entry_handle": "chg_...", "expected_revision": 1 }
  }
}

The public changelog page returns 404 until the project's public pages are published. Ask your agent to run public.publish once.

• The Changelog entries screen lists every entry with its state. People review entries there; the agent edits and publishes them.
• Deleting an entry is destructive. It waits until an owner or admin selects "Approve" under "Pending confirmations".
• The dashboard has no button to write a new entry. Entries start with an agent.

1. 1

   Step 1. Open the Changelog entries screen. The row "Heartbeat exit codes" shows Published.

2. 2

   Step 2. Open the project's public changelog page. It lists the entry.

changelog.get_settings returns not found

The project has no changelog yet. The first changelog.upsert_draft creates it.

The public changelog page returns 404

The public pages are not published. Run public.publish once.