Audit log API を使用する
注: Webhook は、特定のユース ケースの監査ログまたは API ポーリングの代替策として適している場合があります。 Webhook は、リポジトリ、Organization、または Enterprise で特定のイベントが発生したときに GitHub がサーバーに通知する方法です。 Enterprise、Organization、またはリポジトリで特定のイベントが発生したときに学習してログを記録するだけの場合、API や監査ログの検索と比較して、Webhook がより効率的である可能性があります。 詳しくは、「Webhook ドキュメント」を参照してください。
REST API を使用して監査ログを操作することで、エンタープライズのコンプライアンスを維持し、知的財産を保護できます。 監査ログ API を使用してアクセスできる特定のイベントの詳しい情報については、次の記事を参照してください。
監査ログには、Enterprise に影響するアクティビティによってトリガーされるイベントの一覧が表示されます (過去 180 日以内) 監査ログには、Git イベントが 7 日間保持されます。
既定では、過去 3 か月のイベントのみが表示されます。 古いイベントを表示するには、created パラメーターを使って日付範囲を指定します。 詳しくは、「検索構文を理解する」を参照してください。
API 応答のタイムスタンプと日付フィールドは UTC エポック ミリ秒単位で計測されます。
API を介して read:audit_log スコープを使って、監査ログにアクセスできます。
各監査ログ API エンドポイントのレート制限は、ユーザーと IP アドレスの特定の組み合わせに対して 1 時間あたり 1,750 クエリです。 レート制限を回避するために、監査ログ API に対してクエリを実行する統合では、1 時間あたり最大 1,750 クエリの頻度でクエリを実行する必要があります。 さらに、統合がレート制限エラー (通常は 403 または 429 応答) を受け取った場合は、API に対して別の要求を行う前に待機する必要があります。 詳しくは、「REST API のレート制限」と「REST API を使用するためのベスト プラクティス」をご覧ください。
監査ログ REST API の詳細については、「エンタープライズ監査ログの REST API エンドポイント」と「Organization の REST API エンドポイント」を参照してください。
例 1: 特定の日付を対象としたエンタープライズ内のすべてのイベント (ページ分割あり)
カーソル ベースの改ページ位置の自動修正を使用できます。 改ページ位置の自動修正について詳しくは、「REST API 内での改ページ位置の自動修正の使用」をご覧ください。
次のクエリは、avocado-corp エンタープライズで 2022 年 1 月 1 日に作成された監査ログ イベントを検索し、ページネーションを使用して 1 ページあたり最大 100 件の項目で最初のページを返します。 改ページ位置の自動修正について詳しくは、「REST API 内での改ページ位置の自動修正の使用」をご覧ください。 --include フラグを指定すると、応答と共にヘッダーが返されます。
curl --include -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&per_page=100"
結果が 100 を超える場合、link ヘッダーには、次のページ、1 ページ目、前のページの結果をフェッチするための URL が含まれます。
link: <https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42NjQzODMzNTk5MjdlKzEyfDloQzBxdURzaFdVbVlLWjkxRU9mNXc%3D&before=>; rel="next",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=>; rel="first",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=MS42Njc4NDA2MjM4MzNlKzEyfExqeG5sUElvNEZMbG1XZHA5akdKTVE%3D>; rel="prev"
対応するページネーション リンクを次の要求にコピーします。 次に例を示します。
curl -I -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42Njc4NDA2MjM5NDFlKzEyfHRYa3AwSkxUd2xyRjA5bWxfOS1RbFE%3D&before="
例 2: 特定の日付とアクターを対象としたエンタープライズにおける pull request のイベント
created と actor のように複数の検索語句を指定するには、整形された URL の中で + 記号または ASCII 文字コード %20 で区切ります。
次のクエリは、イベントが avocado-corp エンタープライズで 2022 年 1 月 1 日以降に発生し、アクションが octocat ユーザーによって実行された pull request の監査ログ イベントを検索します。
curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"
例 3: 特定の日付とアクターを対象としたエンタープライズにおける Git アクティビティのイベント
URL にパラメーターとして include=git を追加することで、エンタープライズ内の Git イベント (複製、フェッチ、プッシュなど) を検索できます。 または、Web イベントと Git イベントの両方を検索するために include=all を使用できます。
次のクエリは、イベントが avocado-corp エンタープライズで 2024 年 1 月 1 日より後に発生し、アクションが octocat ユーザーによって実行された Git アクティビティの監査ログ イベントを検索します。
curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git"