コンテンツへスキップ

開発者向けドキュメント

最終更新日 2026年11月9日。

Changeloopがあなたのために公開するものはすべて、HTTPS上のシンプルなJSONです。インストールするSDKも、ローテーションするAPIキーも、サインインの手順もありません。以下の2つのフィードは、あなたのフィードIDをキーとした匿名の公開読み取りです。このページのどの例でも、YOUR_PUBLIC_IDを自分のものに置き換えてください。

始める前に知っておくべきこと:あなたの公開フィードIDはアプリ自体にあります。サインインして設定を開くと、デフォルトで表示される「公開フィード」セクションに、changelog.jsonとroadmap.jsonへのすぐに使えるリンク、ホスト型フィードページへのリンク、下記のウィジェットのスニペットとともに表示され、それぞれに独自のコピーボタンがあります。

はじめに

登録から自分のサイトにchangelogを載せるまで、5つのステップで進めます。アプリの「Get started」ページが順番に案内し、終わったステップにはチェックが付きます。

  1. ソースを接続します。GitHubリポジトリ、GitLabプロジェクト、Bitbucketリポジトリのいずれかです。
  2. エントリを書く言語を選びます。
  3. 必要に応じてタグを作成し、読者がプロダクトの領域ごとに絞り込めるようにします。
  4. 最初のエントリを公開します。マージされた変更は下書きとしてレビューボックスに届きます。承認するか、そのリポジトリの自動公開をオンにしてください。
  5. サイトに載せます。ホストされたページにリンクする、ウィジェットを貼り付ける、または自分のページでJSONフィードを表示します。

約10行のReactで作るあなたのchangelog

これをコンポーネントに貼り付けるだけで、動作するchangelogが完成します。それ以上追加する必要はありません。

import { useEffect, useState } from 'react';

const FEED = 'https://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/changelog.json';

export function Changelog() {
  const [entries, setEntries] = useState([]);
  useEffect(() => {
    fetch(FEED).then((r) => r.json()).then((feed) => setEntries(feed.data));
  }, []);
  return <ul>{entries.map((e) => <li key={e.id}><b>{e.title}</b><p>{e.mdContent}</p></li>)}</ul>;
}

mdContentは、エントリのmarkdownをテキストとして返したものです。下のmarkdownフィードのセクションで説明するとおりにフィルタリングされているため、その中の<は&lt;として届きます。フォーマット済みの出力をレンダリングしたい場合は、代わりにhtmlContentを使用してください。これはサーバー側で当社独自のサニタイザーによって、許可されたタグと属性の固定リストから構築されており、これらのレスポンスの中でマークアップとして挿入することを意図した唯一の値です。画像をオンにすると、リストにあるホストのhttps画像に限ってimg要素を含むこともあり、それぞれにreferrerpolicy="no-referrer"が付きます。それ以外はすべてテキストであり、公開リポジトリから作成されたエントリは、そこでプルリクエストを開ける誰にでも影響を受ける可能性があるため、それに応じて扱ってください。

changelogフィード

GET/v1/public/YOUR_PUBLIC_ID/changelog.json

公開されたエントリを最新のものから順に、同一のタイムスタンプの場合は最新のIDで同点を解消します。

クエリパラメータ

  • reposは、acme/web,acme/apiのようにカンマ区切りのリポジトリ完全名のリストを受け取ります。それらのリポジトリからのエントリのみが返されます。指定しなければすべて取得します。
  • limitは、1ページあたりに欲しいエントリの数です。デフォルトは20で、50を超える値は50に制限され、正の数として解釈できない値は失敗する代わりに20に戻ります。
  • cursorは不透明です。前回のレスポンスのnextCursorの値を取得し、そのまま返してください。デコードできないカーソルは、カーソルがないものとして扱われるため、エラーの代わりに最初のページが再度返されます。

レスポンス

{
  "data": [
    {
      "id": "66b0c1f2e4a9d1c3b5a70011",
      "title": "Saved views on the inbox",
      "mdContent": "You can now pin a filter and come back to it.",
      "htmlContent": "<p>You can now pin a filter and come back to it.</p>",
      "headerImage": null,
      "repoFullName": "acme/web",
      "category": "feature",
      "tags": ["Inbox"],
      "learnMoreUrl": "https://acme.example/docs/saved-views",
      "publishedAt": "2026-08-06T09:12:44.000Z"
    }
  ],
  "nextCursor": null,
  "tagColors": { "Inbox": "#4f46e5" },
  "language": "en",
  "roadmapEnabled": true,
  "feedbackEnabled": true,
  "subscriptionsEnabled": false,
  "shippedEmailsEnabled": false,
  "reactionsEnabled": false,
  "feedbackBoardEnabled": false,
  "imageHosts": []
}

各エントリは同じ10個のキーを持ちます:id、title、mdContent、htmlContent、headerImage、repoFullName、category、tags、learnMoreUrl、publishedAt。絵文字リアクションをオンにしている場合、各エントリはさらにreactionsを持ち、5つの絵文字それぞれの件数が入ります。categoryはfeature、fix、internalのいずれかで、作成者が設定しなかった場合はnullになります。publishedAtはISO 8601形式の文字列で、htmlContentは作成者を一度も経由していないエントリでは空文字列になります。headerImageは、エントリに画像リストにあるホストのヘッダー画像がない限りnullで、ある場合はurlとaltを持つオブジェクトになります。tagsはあなた自身のプロダクト領域名の配列で、割り当てがない場合は空になります。learnMoreUrlはレビュアーが追加しない限りnullで、各タグを描画する色はエントリではなくレスポンスのtagColorsマップから取得されるため、語彙から削除したタグは単に色なしでレンダリングされます。末尾に到達するとnextCursorはnullになります。レスポンスの残りの部分は、あなたの設定で何がオンになっているかをページに伝えます。languageはあなたのchangelogの言語コードです。roadmapEnabledとfeedbackEnabledは、RoadmapタブとFeedbackタブに表示するものがあるかどうかを示します。subscriptionsEnabled、shippedEmailsEnabled、reactionsEnabled、feedbackBoardEnabledは「設定」のスイッチに従います(購読にはチームプランも必要です)。imageHostsはあなたの画像ホストのリストで、画像がオフの間は空です。

不明なフィードIDは{"error":"not_found"}を伴う404を返し、不正な形式のものも同様です。この2つは意図的に区別できないため、このエンドポイントを使ってどのIDが存在するかを調べることはできません。

roadmapフィード

GET/v1/public/YOUR_PUBLIC_ID/roadmap.json

あなたのチームがすでに手動で管理している同じ3つのカラム。

{
  "columns": [
    { "column": "planned", "items": [], "hasMore": false },
    {
      "column": "building",
      "items": [
        {
          "id": "66b0c1f2e4a9d1c3b5a70042",
          "column": "building",
          "publicTitle": "Slack notifications",
          "publicDescription": "Post each published entry to a channel you pick.",
          "publishedAt": "2026-08-05T16:20:01.000Z"
        }
      ],
      "hasMore": false
    },
    { "column": "shipped", "items": [], "hasMore": false }
  ]
}

columnsはカラム名でキー付けされたオブジェクトではなく配列であり、その順序は契約の一部です:planned、次にbuilding、次にshipped。空のものも含め、3つとも常に存在するため、「そのカラムが存在しない」と「まだ何も入っていない」を区別する必要は一切ありません。受け取った順序でレンダリングすれば、当社が構築する他のあらゆる表面と一致します。

アイテムはちょうど5つのキーを持ちます:id、column、publicTitle、publicDescription、publishedAt。publicDescriptionは常に文字列で、空になることはあってもnullになることはありません。アイテムの元になったissueについての情報はここでは一切公開されません。リポジトリもissue番号も含まれず、これは意図的なものであり、後で埋める予定の見落としではありません。

このエンドポイントはクエリパラメータを一切受け付けません。カーソルもlimitもリポジトリフィルタもありません。roadmapは無限に成長するログではなく、人がキュレーションする小さなボードだからです。各カラムは最大50件のアイテムを返し、それ以上あった場合はhasMoreを設定します。hasMoreは情報提供のみが目的です:それに従うカーソルは存在しないため、それを中心にページネーションを構築しないでください。

publicTitleとpublicDescriptionは、issueのタイトルと本文から作成された平文であり、公開リポジトリではissueを開ける誰にでも影響を受ける可能性があります。HTMLサニタイズの保証は一切なく、htmlContentの例外でもありません。テキストとしてレンダリングしてください。

埋め込みウィジェット

何も構築したくない場合は、この2行を挿入してください。ウィジェットはshadow root内にレンダリングされるカスタム要素なので、あなたのスタイルを継承することも、そこに漏れることもありません。

ウィジェットのガイドを単独ページで読む

<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
  data-public-id="YOUR_PUBLIC_ID"
  data-api="https://api.changeloop.dev"></changelogapp-widget>

両方の属性が必須です。data-public-idはあなたのフィードID、data-apiはウィジェットがデータを取得するオリジンです。どちらかが欠けていると、要素はコンソールにエラーを書き込み、何もレンダリングしません。ウィジェットがあるべき場所に空白が見える場合、最初に確認すべきことです。

要素に data-theme="dark" を付けるとダークで描画されます。ページ側で実行時に切り替えることもできます。さらに細かくスタイルを調整したい場合、ウィジェットは CSS カスタムプロパティ(--changelogapp-text、--changelogapp-bg、--changelogapp-accent など)と ::part() 名を公開しており、あなた自身のスタイルシートで設定できます。両方のテーマは、設定の「公開フィード」でライブプレビューできます。

data-repos を追加すると、一部のリポジトリだけを表示できます。たとえば複数のプロダクトが 1 つのアカウントを共有している場合に、あるプロダクトのサイトにそのプロダクトの changelog だけを出す、といった使い方です。値は owner/repo 形式のフルネームをカンマで区切ったリストです。所有者を省いた名前は何にも一致せず、エラーなしで空のフィードが表示されます。対象になるのは最大 10 リポジトリです。絞り込んだウィジェットには Updates と Feedback のタブだけが表示されます。ロードマップにはリポジトリ単位の表示がないためで、フィードバックは引き続きチームのフィードバック送信先に登録されます。設定の「公開フィード」には、この属性を自動で書き出すセレクターがあります。

次の順序で3つのタブをレンダリングします:Updates、Roadmap、Feedback。最初の2つは上記のフィードを読み取ります。3つ目は下記のエンドポイントに送信し、各送信のIDをlocalStorageに保存するため、訪問者は戻ってきて送信したものがどうなったかを確認できます。

スクリプトはバージョン付きで提供されます。/widget.jsは常に最新のビルドを提供し、1時間キャッシュされるため、あなたが何もしなくてもリリースは訪問者に届きます。/widget-vN.jsは1つのビルドを固定します:バージョン番号が一度提供されると、そのバイトは二度と変わらず、1年間キャッシュされます。変更を意図的に採用したい場合は固定してください。

1ページにつきウィジェットスクリプトを正確に1つ読み込む

2つのURLは代替であって、レイヤーではありません。どちらも同じカスタム要素名を登録し、ブラウザはドキュメントごとに名前を一度しか登録できないため、先に実行されたスクリプトがそのページの生存期間中は勝ち、2つ目は無効になります。したがって、/widget.jsと/widget-v5.jsの両方を含むページは、ブラウザが先に実行した方をレンダリングします。これはあなたが制御できるものではなく、既存の/widget.jsの隣にバージョン固定のために/widget-v5.jsを追加しても何も起こりません。

これが起こると、ウィジェットは両方のビルドを名指ししてコンソールに警告を書き込むため、推測に頼る必要はありません。それは警告以上のことはできません:2つ目のコピーが実行される頃には、1つ目がすでにその名前を確保しているからです。修正方法は常に、別のスクリプトを追加するのではなくスクリプトタグを置き換えることです。タグマネージャーや部分テンプレートがあなたの代わりに挿入する場合も同様です。継続的なビルドから固定されたビルドに移行するには、srcを変更してください。

リリースのポップアップについて読む

ホスト型フィードページ

https://feed.changeloop.dev/feed/YOUR_PUBLIC_ID

当社はその住所にシンプルなページもホストしています:あなたのchangelogとroadmapボードが、上記と同じ2つのフィードからレンダリングされます。サインインもあなた側での設定も不要です。ループが閉じたときに人々を送り返す先でもあります:GitHub issueに残すShippedコメントはここにリンクし、上記の送信検索からのshippedEntry.linkも同様に、両方とも配信されたエントリの独自の#entry-IDアンカーにたどり着きます。これは、その後別のページに移動していてもエントリを見つけます。

これを統合ではなくフォールバックとして扱ってください。あなたのサイトにこれを配置して、当社ではなくあなたの製品のように見せる方法は、changelogフィードとウィジェットのままです。このページは、まだそれを行っていない場合や、他に何を構築していてもここを指すループを閉じるリンクのためのものです。

独自ドメイン

DNS や証明書を変更せずに、ホスト型ページを自分のアドレスから配信できます。設定の「カスタムドメイン」で、読者に見せる公開アドレス(例:https://example.com/changelog)を貼り付け、サイト上のそのパスを、そこに表示されるプロキシ先に向けてください。ルールひとつでページ、アセット、データ、フィードのすべてをカバーします。「ドメインを確認」は当社側からあなたのアドレスを取得し、プロキシが正しいか、正しくなければ何を変えるべきかを教えます。

MCPサーバー

MCPサーバーのガイドを単独ページで読む

POSThttps://api.changeloop.dev/mcp

Claude Code、ChatGPT、またはModel Context Protocolに対応する他のエージェントで作業している場合は、あなたのchangelogに直接接続できます。エージェントは、レビュー待ちのものを確認し、文言を編集し、エディタを離れることなく公開できます。これはウェブアプリと同じレビューゲートです:何かが承認するまで、何も公開されません。

Claude Codeの接続

まずAPIキーを作成し(設定、APIキー)、その後ヘッダーにキーを含めてサーバーを追加します:

claude mcp add --transport http changeloop \
  https://api.changeloop.dev/mcp \
  --header "Authorization: Bearer clapi_YOUR_KEY"

代わりにJSON設定を読み取るクライアントの場合、同じことは次のようになります:

{
  "mcpServers": {
    "changeloop": {
      "type": "http",
      "url": "https://api.changeloop.dev/mcp",
      "headers": { "Authorization": "Bearer clapi_YOUR_KEY" }
    }
  }
}

まだOAuthフローはありません。認証はヘッダー内のAPIキーであり、上記の2つのコマンドが行っていることです。設定でそのキーを取り消すと、次のリクエストでエージェントが切断されます。

エージェントができること

10個のツールがあり、リストは意図的に短くしています。この製品ができる他のことはすべて、同じキーでREST API経由で利用できます。エージェントに公開される各ツールは、それを呼び出すよう説得され得るもう1つの手段です。

  • list_pending_entries、list_published_entries、get_entry - あなたのエントリを読み取ります。保留中のものは公開されていません。
  • update_entry - エントリのタイトルまたはmarkdown本文を変更します。フィードが提供するHTMLは、あなたのmarkdownから当社のサニタイザーによって再レンダリングされます。エージェントはHTMLを提供できません。
  • approve_entry - 公開します。これは公開かつ即時であり、GitHub上のリンクされたフィードバックに通知します。承認できるのは保留中のエントリのみですが、publish_now: trueを渡せば予約済みのエントリも承認でき、予定の時刻を待たずに今すぐ公開されます。
  • discard_entry - エントリをchangelogから除外します。ウェブアプリから元に戻せます。
  • get_changelog_info - あなたのフィードIDとchangelogが提供されているアドレス。
  • list_scheduled_entries、schedule_entry、unschedule_entry - 予約済みのエントリを公開が近い順に確認します。保留中のエントリを指定した時刻に公開するよう予約したり、その時刻を変更したりします。時刻はタイムゾーン付きで指定し、1分後から90日後までの範囲です。予約を取り消すと、エントリは保留中に戻ります。まとめ投稿は予約できません。

できないこと

すべてのツールはキーが属するチームに限定されており、どれも引数としてチームを受け取らないため、何かが試みても他のチームを指すものは何もありません。サーバーはブラウザセッションを受け付けず、キーのみを受け付けます。リクエストは意図的に認証情報を添付する必要があります。また、キーはキーを管理することも、データエクスポートをダウンロードすることもできないため、この方法で接続されたエージェントは、自分自身に2つ目の認証情報を発行することも、1回の呼び出しであなたのデータを引き出すこともできません。

APIキー

上記はすべて匿名であり、認証情報を必要としません。認証されたAPI - あなたの設定、あなたのレビューボックス - は別の表面であり、サインイン済みのブラウザセッションまたはAPIキーのいずれかを受け付けます。キーはスクリプトとエージェントのためのものです:キーボードに人がいない状態であなたのchangelogに到達する必要のあるものすべて。

Authorization: Bearer clapi_YOUR_KEY

アプリの「設定」の「APIキー」タブで作成します。キーは作成した瞬間に一度だけ表示され、二度と表示されません。当社はそのハッシュのみを保存するため、二度目にそれをあなたに表示できる画面はどこにもありません。紛失した場合は、それを取り消して別のキーを作成してください。

キーができることとできないこと

キーは、それが作成された単一のチームに限定された、サインインと同じアクセス権を持ちますが、2つの意図的な例外があります。APIキーを管理することも、データエクスポートをダウンロードすることもできません。どちらも実際のサインインが必要です。これにより、漏洩したキーが自分自身の代替品を発行することも、それをブロックするために使うキーを取り消すことも、1回のリクエストであなたのチームのデータを引き出すこともできません。

取り消し

取り消しは次のリクエストで有効になります。取り消されたキーは不明なキーとまったく同じように401を返し、有効なセッションをまだ保持しているブラウザからでも401を返し続けます。Authorizationヘッダーを含むリクエストは、cookieリクエストとして黙って再試行されることは決してないためです。取り消されたキーは、取り消された日付と最後に使用された日付とともにリストに残ります。これは、漏洩したキーがどこに到達したかを解明する際に必要なものです。

プランと上限

無料プランは月に 20 件のマージ済み変更を記事化し、1 日あたりの確認するマージ数、トリアージするフィードバック数、下書きするロードマップカード数、代替バージョン数をそれぞれ 50 に制限します。チームプランには月間の上限がなく、1 日あたりの上限も通常の 1 日をはるかに上回る水準です。確認するマージは 500 件、代替バージョンは 200 件、翻訳は 200 件までです。設定の「プランと使用量」は、製品自身が数える通りに各予算を表示し、それぞれがリセットされる時刻も、何かが拒否される前に示します。上限を超えて届いた作業は失われず保留されます。クォータ超過のエントリは受信箱で待機し、拒否されたロードマップの下書きは期間が切り替わればリトライできます。メール購読者(読者が更新をメールで受け取れる機能)はチームプランのみで利用できます。また、どちらのプランでも、すべてのチームに不正利用を防ぐための上限がいくつかあります。購読確認メールとリリース通知メールはそれぞれ 1 日 200 通まで、1 つのエントリが得られるリアクション数と 1 つの要望が得られる票数にも、1 時間と 1 日ごとの上限があります。これらを超えると、超過分のメールは送信されず、超過分のリアクションや票は期間が切り替わるまで受け付けられません。

GitLabとBitbucket

GitLabプロジェクトまたはBitbucketリポジトリは、GitHubリポジトリと同じ方法であなたのchangelogにフィードできます:設定のGitLab、または設定のBitbucketで接続し、当社が提供するwebhookを追加する(bitbucket.orgでは、BitbucketのページにそのボタンがあればConnect with Bitbucketに追加を任せる)と、あなたが指定したブランチにマージされたすべての変更が、同じ方法で書かれ、同じ人間によるレビューを経る、レビューボックス内の下書きエントリになります。エントリは、マージされたプルリクエストまたはマージリクエストから作成されます。GitHubとBitbucketでは、設定のWhat creates draftsでプッシュモードを選んだ場合はプッシュからも作成されます。GitLabプロジェクトはマージリクエストからのみ下書きを作成します。

プロジェクトの接続

GitLabプロジェクトは設定のGitLabで、Bitbucketリポジトリは設定のBitbucketで接続します。パス(GitLabではacme/webのようなグループとプロジェクト、Bitbucketではacme/appのようなワークスペースとリポジトリ)を入力すると、当社はwebhookアドレスとシークレットを返します。両方を相手側のwebhook設定に貼り付けてください:GitLabではMerge request eventsにチェックを入れ、BitbucketではMerged pull requestトリガーとPush repositoryトリガーの両方にチェックを入れてください。セルフホスト型のインスタンスはhttps経由で動作します。シークレットはその瞬間に一度だけ表示されます。紛失した場合は、プロジェクトを削除して再度接続してください。bitbucket.orgの場合、BitbucketのページにConnect with Bitbucketボタンが表示されていれば、貼り付けを省略できます:そのボタンを押してアクセスを一度許可すると、当社がリポジトリのメインブランチを読み取り、webhookを追加します。リポジトリの管理者権限が必要です。セルフホスト型のBitbucketの場合、または手動で貼り付けたい場合は、Set it up by handを選ぶと、上記のとおりアドレスとシークレットが表示されます。Bitbucketのリポジトリを削除して再接続する場合は、Bitbucket側の古いwebhookもRepository settings、次にWebhooksから削除してください。プロジェクトを接続した後は、そのプロジェクトの行でブランチを変更したり、自動公開をオンにしたりできます。配信が無視された場合は、その行に理由が表示されます。

なぜBitbucketはブランチを尋ね、GitLabは尋ねないのか

GitLabは、あなたのプロジェクトがデフォルトとして扱っているブランチを当社に伝えるため、フィールドを空白のままにして、まさにそれを意味することができます。Bitbucketはデフォルトのブランチを一切送信しないため、空白のままにすることを許してしまうと、比較対象がなくなり、あなたのwebhookは完璧にインストールされているように見えながら、一件もエントリを生成しないままになってしまいます。当社は、それが起こるのを許すよりも、一つの質問をすることを選びます。Connect with Bitbucketを使うと、アクセスを許可した時点で当社がBitbucketにメインブランチを問い合わせるため、入力する必要はありません。

まだカバーしていないこと

changelogエントリだけであり、それ以外はありません。あなたのためにissueを提出するフィードバックウィジェット、修正が配信されたときにそのissueに投稿される返信、issueラベルによって動く公開roadmap、レビューボックス内のソースプレビューは、今日はすべてGitHub専用です。

理由は、覆い隠すよりも述べることを選ぶものです。これらそれぞれが、当社が保持する、あなたのプロジェクトへの書き込み権限を持つアクセストークンを必要とします。changelogエントリはどちらも必要としません。それらが書かれる元になるものはすべてwebhook自体に届くため、GitLabやBitbucketをwebhookで接続しても、当社に認証情報が渡されることも、あなたのコードの読み取りが行われることもありません。Connect with Bitbucketは唯一の例外です。Bitbucketは1回のリクエストに限り、リポジトリとプルリクエストの読み取り、およびwebhookの管理ができるトークンを当社に貸与します。当社はそれをメインブランチの読み取りとwebhookの追加にのみ使用し、その後破棄します。何も保存されません。当社は、機能リストを完成させるためにトークンを要求するよりも、あなたに何のコストもかからない部分を提供することを選びます。

エントリの他のバージョン

1つの変更は通常、複数回説明する必要があります:changelogで顧客に、それについての質問に答える人に、そして誰も4段落を読まないチャンネルで。レビューボックスから、エントリを承認する前に、2つの追加バージョンのうちの1つを作成できます。

アナウンスバージョンは1~2行で、エントリを承認したときに全文の代わりにSlackに投稿されるものです。サポートノートは社内向けブリーフィングです:何が変わったか、顧客が何に気づくか、サポート担当者がほぼそのまま言えるような一文。どちらも、使用される前に書き直せる下書きであり、どちらも削除できます。

どちらも公開されません

これらのバージョンは、あなたのchangelogページ、どのフィード、ウィジェット、それらを提供するAPIにも一切表示されません。特にサポートノートは、あなたの会社内の人々のために書かれており、エントリ自体よりも率直な場合があります。それが存在する唯一の場所は、あなたのレビューボックスと、使用している場合はあなた自身のコピーです。

何から書かれるか

常にエントリから書かれ、プルリクエストからは決して書かれません。これは意図的なものです:エントリはすでに、セキュリティ修正を曖昧に保つルールと、あなた自身のレビューを経ています。そこから書き直されたバージョンは、あなたが削除した詳細を再び持ち込むことはできません。その詳細はモデルに与えられたものの中にないからです。

予約公開

エントリを今すぐ公開する代わりに、公開する日時を指定できます。レビューボックスで「承認」の横にある「スケジュール」を押し、日時を選んでください。時刻はあなた自身のタイムゾーンで指定し、保存する前に、実際に公開される正確な時刻がアプリに表示されます。

その時刻までは、エントリは公開中の changelog、ウィジェット、ポップアップ、フィードのどこにも表示されません。その間も、エントリを編集したり、別の時刻に移したり、予約を取り消したり、今すぐ公開したりできます。予約済みのエントリには、レビューボックスに専用のタブがあります。

予定の時刻になると、エントリは承認した場合とまったく同じように公開されます。changelog に表示され、リンクされたフィードバックにはリリースされたことが伝えられ、Slack チャンネルとメール購読者も、オンにしていれば通知を受け取ります。publishedAt は実際に公開された時点で、通常は指定した時刻の 1、2 秒後です。予約できるのは 90 日先までです。

まとめ投稿は、日次または週次の独自のスケジュールがあるため、この方法では予約しません。予約済みのエントリはまとめ投稿に含まれません。

エントリ内の画像

エントリにはスクリーンショットを表示できます。エントリ本文の画像は、markdown の通常の書き方どおり ![description](https://...) と書きます。さらにエントリごとに 1 枚、タイトルの上に表示するヘッダー画像も設定できます。画像は、ウィジェットとそのポップアップのカード、ホスト型ページ、RSS と JSON Feed、購読者に届くメールに表示されます。画像は必ず、リストにあるホストから https で、リファラーなしで読み込まれます。エントリ本文は、接続したリポジトリでプルリクエストを開ける人なら誰でも左右でき、ほかのホストの画像は changelog を読む人の追跡に使われるおそれがあります。そのため、それ以外の画像は取得されず、「Image:」に説明を続けたプレーンテキストとして表示されます。

画像は、アプリの「設定」の「公開フィード」の「画像」でホストのリストを保存するまでオフです。ホストを 1 つも保存していなければ、どこにも画像は読み込まれません。GitHub のスクリーンショット用ホストはワンクリックで追加できます。現在プルリクエストに貼り付けたスクリーンショットが置かれる github.com/user-attachments/assets/ と、それより古いものが置かれる user-images.githubusercontent.com です。リストには最大 15 個のホストを登録でき、それぞれ images.example.com のような正確なホスト名で指定します。ワイルドカードは使えません。ホストを削除すると、そのホストの画像はすぐに表示されなくなります。

エントリにヘッダー画像を付けるには、レビューボックスでエントリを編集し、画像の https リンクと、画像を見られない人のための短い説明を貼り付けます。アプリが保存するのは、ホストがリストにあるヘッダー画像だけです。JSON フィードではエントリの headerImage になり、ヘッダー画像がない場合は null です。

非公開の GitHub リポジトリのスクリーンショットが、公開の場で表示されることはありません。GitHub はそれを、そのリポジトリへのアクセス権を持ってサインインしている人にしか配信しないため、ウィジェットでは読者に画像の説明が表示され、ホスト型ページ、フィードリーダー、メールでは壊れた画像が表示されます。非公開リポジトリの場合は、スクリーンショットを公開の場所に置き、そのホストをリストに追加してください。

画像を有効にしている場合、自動公開は画像の表示されないエントリを公開しません。エントリの本文やヘッダー画像がリストにないホストを使っている場合、自動公開はリポジトリの場合もまとめ投稿の場合も、そのエントリを公開せずにレビューボックスに保留し、画像が表示されないホストを示します。ホストを追加するか、画像を削除するか、そのまま承認してください。そのまま承認すると、読者には画像の代わりに説明が表示されます。下書きが独自に画像を加えることはありません。下書き内の画像は、プルリクエストや、まとめ投稿が対象とするエントリなど、必ず下書きの元になった内容から来ています。画像が無効の間は、自動公開はこれまでどおりに動作し、読者には各画像の代わりにその説明が表示されます。

サイトが Content-Security-Policy ヘッダーを送信している場合、ウィジェットが表示できるのは、ポリシーの img-src で許可したホストの画像だけです。画像をオンにすると、「設定」の「公開フィード」に使うべき行が表示されます。詳しくはウィジェットのガイドの Content-Security-Policy の項で説明しています。ホスト型ページについては何もする必要はありません。そのポリシーはあなたのリストに従います。

Changeloop は画像をホストしません。画像とは、GitHub のプルリクエストに貼り付けたスクリーンショット、あなた自身のサイト、利用している CDN など、すでにどこかにある画像へのリンクです。そこにあるファイルが変わったり消えたりすれば、changelog 内の画像も同じように変わったり消えたりします。

Slackでのアナウンス

エントリを承認すると、公開されるのと同じ瞬間にSlackチャンネルに投稿できます。設定の「Slack」タブで接続してください:自分のワークスペースで受信webhookを作成し、チャンネルを選び、URLを貼り付けます。そのwebhook以外は、あなた側で何もインストールされず、当社があなたのワークスペースへのアクセスを求めることは一切ありません。

メッセージには、エントリのタイトル、あなたが承認したままのテキスト、そのカテゴリとタグ、そしてあなたのchangelog上のエントリへのリンクが含まれます。Markdownは、Slackが実際にレンダリングするものに変換されるため、エントリが独自のアスタリスクを表示したまま届くことはありません。

webhookのURLは認証情報です

そのURLを持つ人は誰でもチャンネルに投稿できるため、当社はそれをパスワードのように扱います:保存された後、あなた自身のデータエクスポートを含め、どの画面もどのAPIレスポンスも二度とそれを表示しません。その後見えるのはマスクであり、2つのwebhookを区別するには十分ですが、他の誰にとっても役に立ちません。当社はhooks.slack.comのアドレスのみを受け付けるため、誤入力または置き換えられたURLは取得される代わりに拒否されます。

動作しなくなるとき

Slackでアプリを削除したり、チャンネルをアーカイブしたりすると、webhookは永久に動作しなくなります。当社は最初の拒否されたメッセージでそれに気づき、アナウンスをオフにし、理由と日付とともにSlackタブでそれを示します。静かに再試行を続けないのは意図的なものです:誰もアナウンスしなかったchangelogは、誰も読まなかったものとまったく同じに見えます。これは伝える価値のある違いです。

一時停止

一時停止はアナウンスを停止しwebhookを保持するため、再開はSlackを通じてもう一度手続きするのではなく、1回のクリックで済みます。切断はURLを完全に削除します。いずれにせよ、公開自体には影響ありません。Slackはあなたのchangelogが投稿するチャンネルであり、待機するゲートでは決してありません。何かを承認したときにSlackに到達できない場合でも、エントリは公開され、アナウンスは自動的に再試行されます。

RSSとJSON Feed

RSSとJSON Feedのガイドを単独ページで読む

GEThttps://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/rss.xmlGEThttps://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/feed.json

同じ公開エントリを、読者が理解する2つの形式:RSS 2.0とJSON Feed 1.1で購読可能なフィードとして提供します。どちらもchangelogフィードと同じrepos、category、tagフィルターを受け付け、同じCache-ControlとETagを持ちます。どちらもページネーションしません:読者はフィードの先頭をポーリングするため、これらはカーソルなしで最新のエントリのみを返します。

エントリのテキストはサニタイズされたHTMLで、RSSではCDATAに包まれ、JSON Feedではcontent_htmlとして提供されます。画像をオンにすると、そこに画像も含まれます。エントリのヘッダー画像は、RSSではmedia:content要素、JSON Feedではアイテムのimageになります。JSON Feedはさらに、名前空間付きの_changelogapp拡張の下にあなたのタグの色を含みますが、RSSは含みません。それらを描画する読者がいないためです。

ホスト型ページは両方をrel="alternate"リンクとして宣伝するため、そこにたどり着いたブラウザや読者は、パスを教えられなくても購読できます。

単独のエントリ

GEThttps://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/entries/ENTRY_ID

1つの公開エントリを返します。これは、changelogフィードがそのdata配列で運ぶのと同じオブジェクトです。これは、フィード内の永続リンクが指す先であり、IDがあってそれを見つけるためにフィードをページネーションしたくない場合に便利です。不明なID、または公開されていないエントリに属するIDは、他の不明なIDと同じ本文で404を返します。

markdownフィード

GEThttps://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/changelog.md

同じ公開エントリを、text/markdownとして提供されるプレーンなmarkdownとして提供します。これはブラウザではない読者のために存在します:「この製品に最近何が変わったか」に答えるLLMやエージェントは、RSSをパースしたりJSONをたどったりすることなくテキストを取得します。changelogフィードと同じrepos、category、tagフィルターを受け付け、同じCache-ControlとETagを持ち、他の2つとまったく同じように条件付きリクエストに304で応答します。

各エントリはセクションです:見出しとしてのタイトル、次に日付・カテゴリ・任意のタグを含む1行、次にリストにあるホストのヘッダー画像がエントリにあればmarkdownの画像行としてのヘッダー画像、次にエントリテキスト、次にエントリにあればLearn moreリンク、次にその永続リンク。ドキュメントはあなたのフィードのタイトルと説明で始まり、ホスト型ページへのリンクで戻ります。まだ何も公開されていない場合、空の本文を返す代わりに一文でそれを述べるため、読者はそれを失敗した取得と区別できます。

ホスト型ページは、RSSとJSON Feedのリンクとともに、type text/markdownのrel="alternate"リンクとしてそれを宣伝するため、HTMLを取得したエージェントは、パスを教えられなくてもそれを見つけられます。

提供されるものは、サニタイズされたHTMLではなく、あなたが承認したエントリのmarkdownです。markdownレンダラーがそれをHTMLや意図しない画像に変えられないよう、出力時にフィルタリングされます:すべての<は&lt;として書かれ、リストにあるホストの画像はクリーンなリンクで組み立て直され、それ以外の画像はその説明のプレーンテキストに置き換わり、タイトル、タグ、リンクはエスケープされます。text/htmlとして提供されることは決してありません。自分でレンダリングする場合も、信頼できないmarkdownとして扱ってください:公開リポジトリから作成されたエントリは、そこでプルリクエストを開ける誰にでも影響を受ける可能性があります。

サイトマップ

GEThttps://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/sitemap.xml

1つのchangelogのサイトマップで、検索エンジン向けです。changelogページと、公開エントリそれぞれの永続リンクを、読者に見えるアドレスで掲載します。設定の「カスタムドメイン」で独自ドメインを設定している場合は、そのドメインのアドレスになります。エントリのlastmodはその公開日で、ページのlastmodは最新エントリの公開日です。最新の1000件のエントリを掲載し、フィルターは受け付けず、フィードと同じCache-ControlとETagを持ち、条件付きリクエストには304で応答します。

検索エンジンがこのファイルを自動的に見つけることはありません。また、サイトマップが受け付けられるのは、そのファイルを配信するホスト上のページについてか、そのサイト用に送信された場合だけです。そのため、changelogを置いているドメインについて、このアドレスをサーチコンソールで送信してください。

あなた自身のサイトからフィードバックを収集する

テストする前にオリジンを追加してください

書き込みを行う公開エンドポイントのうち、リクエストの送信元を確認するのはこれだけであるため、どこからでもリクエストを受け付けるわけではありません。ブラウザのOriginヘッダーをチーム単位の許可リストと照合し、そのリストは空から始まります。空とはすべて拒否することを意味し、すべて許可することではありません。埋め込んでいるオリジンを追加するまで、すべての送信は{"error":"origin_not_allowed"}を伴う403を返し、あなたの受信箱には何も届きません。フォームが正しく見えるのにまだ失敗する場合、ほとんど常にこれが原因です。認証済みのPATCHで/v1/settings/feedに{"allowedOrigins": ["https://your-site.example"]}を送ってリストを設定し、同じパスへのGETで読み返してください。これはあなたのpublicId、allowedOrigins、そしてあなたの購読者がフィードリーダーで見るfeedTitleとfeedDescriptionで応答します。当社は各オリジンをブラウザが送信する正確な形式で保存するため、末尾のスラッシュや明示的なデフォルトポートは問題になりません。

POST/v1/public/YOUR_PUBLIC_ID/feedback
POST https://api.changeloop.dev/v1/public/YOUR_PUBLIC_ID/feedback
Content-Type: application/json
Origin: https://your-site.example

{ "email": "someone@example.com", "message": "Dark mode, please." }

202 Accepted
{ "publicSubmissionId": "0ZbQ8yqk3n7T1sVJ4mWpLd2rXfEuGh6A" }

emailはメールアドレスのように見え、254文字以下である必要があります。messageは空でなく、文字数ではなくUTF-8バイトで測定して2KB以下である必要があります。JSON本文全体は8KBに制限されています。もう1つフィールドがあります、website:これはハニーポットなので、省略するか、当社のウィジェットが行うように隠しフィールドとしてレンダリングする場合は空で送信してください。

これで何かをデバッグする前に、ハニーポットを理解しておく価値があります。websiteに何か記入されて届いた場合、当社は完全に普通に見える送信IDとともに202を返し、その後何もしません。捕まったことを知ったボットは単に別の方法で再試行するからです。これはボットにとって正しい応答であり、あなたにとっては紛らわしいものです。あなた自身のフォームにブラウザが自動入力しそうなwebsiteという名前のフィールドがある場合は、名前を変更するか削除してください。受け付けられたように見えて決して現れない送信は、ほとんど常にこれです。

当社が受け付けた送信は、publicSubmissionIdとともに202を返します。それを送信者に返し、可能であれば保存してください:それは、その後何が起こったかを送信者が知る唯一の方法です。

失敗モードは、形式が間違っている場合はinvalid_emailまたはinvalid_messageを伴う400、形式は正しいが大きすぎる場合はemail_too_largeまたはmessage_too_largeを伴う413、1つのアドレスから1つのフィードへの分あたり5回または時間あたり30回を超える送信の場合はrate_limitedを伴う429、origin_not_allowedを伴う403、そして認識できないフィードIDの場合はnot_foundを伴う404です。

また、送信がどれだけの後続作業をトリガーできるかについて、チームごとの1日の上限もあります。それを超えても、届いたものはすべて引き続き受け付けて保存しますが、単に何かを自分自身で開くのではなく、チームの誰かが見るのを待つだけです。

読者からの入力を受け付ける公開エンドポイントはほかに3つあり、どれもオリジンを確認しません。あなたのホスト型ページからも届く必要があるためです。メールでの更新の購読(指定されたアドレスに送るのは確認メール1通だけです)、絵文字リアクションの追加と取り消し、そしてフィードバックボードの要望への投票と、その取り消しです。いずれも機能をオンにするまでは404を返し、アドレスごととチームごとにレート制限されているため、スクリプトで大量に送りつけることはできません。

1件の送信の確認

GET/v1/public/YOUR_PUBLIC_ID/feedback/PUBLIC_SUBMISSION_ID

statusで応答し、その送信に対するissueが存在すればgithubIssueUrlを、作業が完了すればタイトルとリンクを持つshippedEntryを追加で返します。送信者のメールアドレスは、このルートのために当社のデータベースから読み取られることは一切なく、まして返されることもありません。これにより、誰でも見ることができるページでレンダリングしても安全なレスポンスになります。IDはそれ自体が認証情報のすべてであるため、そのように扱ってください。1分あたり20リクエスト、1時間あたり200リクエスト、アドレスとフィードごとに制限されています。

キャッシュ、CORS、条件付きリクエスト

両方のフィードは、強力なETagとともにCache-Control: public, max-age=60, stale-while-revalidate=300を送信します。そのETagをIf-None-Matchとして送り返すと、変更のないフィードは本文なしで304を返します。どのレスポンスフィールドも壁時計の値を持たないため、変更されていないデータを再レンダリングしてもETagは安定したままであり、それがこの304を信頼できるものにしています。

両方のフィードと送信検索は匿名の読み取りであり、Access-Control-Allow-Origin: *で応答するため、どのオリジンからでも、curlからでも、ビルドステップからでも呼び出せます。フィードバックのPOSTは例外です:オリジンが許可されているかにかかわらず、ワイルドカードではなく、あなた自身の許可されたオリジンとVary: Originで応答します。ブラウザはこれに対してプリフライトを行い、プリフライトは常に204で応答するため、あなたの設定を探るために使用することはできません。