Skip to main content
Skip to content

Issue の状態 webhook とワークフロー

Webhook と GitHub Actions ワークフローを使用して、問題の状態が変化したときに応答します。

メモ

問題の状態は プレビュー 内にあり、プレビューに登録されているアカウントでのみ使用できます。 Webhook ペイロードと status_changed アクティビティの種類は変更される可能性があります。

状態変更イベントについて

問題の状態が変わると、GitHubはissues アクションの status_changed webhook イベントを送信します。 すべての issues アクションのペイロードには、問題の現在の状態が issue.status にも含まれます。 これらのイベントを使用して、他のツールを問題と同期させたり、問題が特定の状態に達したときに GitHub Actions ワークフローを実行したりできます。

ステータスは、Issue のステータスを使用するリポジトリ内の Issue にのみ含まれます。 その他の問題の場合、ペイロードには issue.status が含まれず、GitHub は status_changed を送信しません。

完全なペイロード スキーマについては、 Webhook のイベントとペイロード を参照してください。

状態オブジェクト

Webhook ペイロードは、各状態を、3 つのプロパティを持つオブジェクトで記述します。

プロパティタイプDescription
idInteger状態の識別子。
nameString状態の表示名 (たとえば In progress など)。 名前は変更できます。
categoryString状態のカテゴリ ( backlog、 planned、 started、 completed、 not_planned、 duplicateなど)。 今後、その他のカテゴリが追加される可能性があります。

複数のステータスが同じカテゴリに属している可能性があります。 たとえば、[進行中] と [レビュー中] の両方が started カテゴリに属します。 コードまたはワークフローで 1 つのステータスに一致させるには、その idを使用します。 カテゴリ内のすべてのステータスを照合するには、その categoryを使用します。 nameでは一致条件にしないでください。

issue.status は、課題にステータスがない場合は null です。 たとえば、リポジトリで状態が使用可能になる前に作成された問題は、他のユーザーが設定するまで、または問題が閉じられたり、再度開いたりするまで、状態がありません。

status_changed ペイロード

issue、repository、sender、およびすべてのissues ペイロードに含まれるその他のプロパティに加えて、status_changed ペイロードには次のプロパティが含まれます。 このアクションの sender は、状態を変更したユーザーまたはアプリです。

プロパティDescription
status問題が変更された後の状態。
changes.status.from変更前に課題が持っていたステータス。持っていなかった場合は null 。
changes.state.from問題の前の state 、 open または closed。 ステータスの変更によって課題がクローズまたは再オープンされた場合にのみ含まれます。
changes.state_reason.from問題の以前の state_reason 。 状態の変更によって状態の理由も変更された場合にのみ含まれます 。たとえば、問題を閉じたり再度開いたり、閉じた理由を変更したりします。 問題に状態の理由がなかった場合 (たとえば、最初に終了したときなど) は null です。

キャプチャされた値と現在の課題

statusプロパティとchangesプロパティは、保存時の変更を示します。 issue.statusを含む issue プロパティは、配信がビルドされたときの問題を説明します。これは、他のすべてのissuesアクションと同じです。 その前に問題が再度変更された場合、 issue.status は statusとは異なる場合があります。 たとえば、あるユーザーが問題を [進行中] から [レビュー中] に移動した後、すぐに [完了] に移動した場合、最初の変更の配信に [完了] issue.status を設定できます。

特定の変更が何を行ったかを確認するには、 status と changesを使用します。 遅延、再試行、または再配信されたペイロードは古くなる可能性があるため、 issue.status が問題の最新の状態ではない可能性があります。 詳細については、この記事の後半の配達を参照してください。

status_changedが送信されたとき

GitHub は、問題の状態が変更されるたびに status_changed を送信します。これには、問題の作成時、クローズ時、または再オープン時に GitHub が行う変更も含まれます。

  • ステータスの設定: 誰かが課題に別のステータスを選択します。
  • 問題の作成: 新しい問題は、作成したユーザーが別の状態を選択しない限り、バックログの状態を取得します。 changes.status.from は nullです。 GitHub openedに加えてstatus_changedも送信します。
  • 最初の状態の設定: 状態のない既存の課題に状態が設定されます。 changes.status.from は nullです。
  • Issue をクローズまたは再オープンする: Issue を完了としてクローズすると、Done ステータスに設定されます。未計画としてクローズすると、Not planned に設定され、重複としてクローズすると、Duplicate に設定されます。 状態を選択せずに問題を再度開くと、バックログが設定されます。 GitHub は、closed または reopened に加えて status_changed も送信します。
  • pull request のリンク: オープン pull request を、状態がない、またはバックログまたは Todo 状態の未解決の問題にリンクすると、問題が [進行中] に移動します。 sender は、pull request をリンクしたユーザーまたはアプリです。 問題の状態を選択できない場合、状態は変更されません。

GitHub では、次のような場合に status_changed が送信されません。

  • 状態は変更されません。たとえば、誰かが問題が既に持っている状態を選択した場合などです。
  • 問題は別のリポジトリに転送されます。 新しい問題はその状態を保持し、その状態は transferred ペイロードの changes.new_issue.status に含まれます。

問題を閉じたり、再度開いたりする状態の変更

completed、not_planned、およびduplicateカテゴリの状態は、終了した問題に対するものです。 未解決の問題に対してこれらの状態のいずれかを選択すると、問題が閉じられ、クローズされた問題の他のカテゴリの状態が再度選択されます。

状態の変更が課題を終了または再度開くと、 GitHub は 2 つの配信 ( status_changed、 closed または reopened) を送信します。 2 つの配送は、どちらの順序でも到着できます。

終了した問題を別のクローズ理由の状態に変更すると(たとえば「完了」から「未計画」へ)、changes.state を含み、status_changed を含まない changes.state_reason が送信されます。 GitHubは、新しいclosedを含む別のstate_reason配信も送信します。

統合で status_changed と closed または reopenedが処理される場合は、両方の配信によって報告される同じ変更を処理できることを確認します。

配送

GitHub は、他の webhook イベントと同じ方法で status_changed を配信します。 配信はベスト エフォートです。 GitHub では、各変更が 1 回だけ配信されたり、変更が発生した順序で配信が到着したりすることは保証されません。

  • 配信失敗: サーバーが使用できない場合など、配信が失敗する可能性があります。 GitHub では、配信に失敗した配信は自動的に再配信されませんが、再配信することはできます。 詳細については、「webhookの失敗した配信の処理」を参照してください。
  • 繰り返し配信: 同じ配信を複数回受け取ることができます (再配信の場合など)。 再配信には元の配信と同じ X-GitHub-Delivery ヘッダーがあるため、ヘッダーを使用して、既に処理した配信をスキップできます。
  • Order: 配信は順不同で到着する可能性があり、遅延、再試行、または再配信されたペイロードは、 issue.statusを含め古くなる可能性があります。 配送が到着する順序を使用して、問題の最新の状態を判断しないでください。

問題の最新の状態を取得するには、REST API で問題をフェッチします。 詳細については、「問題用の REST API エンドポイント」を参照してください。 組織が所有するリポジトリでは、応答には、GitHub Appインストールとして認証された要求やワークフローでGITHUB_TOKENを使用する要求など、認証された要求のstatusが含まれます。 プレビュー中、個人用アカウントが所有するリポジトリでは、プレビューにアクセスできるユーザーに代わって要求が行われた場合にのみ、statusが応答に含まれます。 応答に statusが含まれていない場合は、後で到着した配信で古い状態が発生する可能性があるため、配信からの状態を慎重に使用します。

状態を変更できるユーザー

リポジトリへのトリアージ アクセス以上のユーザーは、その Issue の状態を選択できます。 追加のアクセス許可ルールは、カスタム ロール、アプリ、ワークフロー、個人アカウントに適用されます。

  • カスタム リポジトリ ロール: 組織が所有するリポジトリでは、Triage、Write、または Maintain ロールを継承するカスタム ロールを持つユーザーが状態を選択できます。 読み取りロールを継承するカスタム ロールを持つユーザーは、ロールが issue タイプを設定できる場合でも、状態を選択できません。
  • アプリとワークフロー: 組織が所有するリポジトリでは、"Issues" リポジトリ権限に書き込みアクセス権を持つGitHub Appsも、GITHUB_TOKEN権限を持つissues: writeを使用するワークフローを含め、状態を選択できます。
  • 個人用アカウント: プレビュー中、個人用アカウントが所有するリポジトリでは、プレビューにアクセスできるユーザーのみが状態を選択できます。

Issue をクローズまたは再オープンするステータスを選択するには、Issue をクローズまたは再オープンするためのアクセス許可も必要です。 クローズされた issue のクローズ理由を(たとえば [完了] から [未計画] に)変更するには、クローズと再オープンの両方のアクセス許可が必要です。

状態を選択できないユーザーは、Issue を閉じたり、再度開いたりすることで、状態を変更できます。 たとえば、問題の作成者は、リポジトリへの読み取りアクセス権を使用して問題を閉じて再度開くことができます。この場合、新しい状態の既定の状態が設定されます。 これらの変更により status_changed も送信され、sender は課題を閉じた、または再度開いたユーザーです。

状態が変更されたときにワークフローを実行する

問題の状態が変化したときにGitHub Actions ワークフローを実行するには、issues イベントのstatus_changed アクティビティの種類を使用します。 ワークフローは、問題の状態が変更されるたびに実行されます。 ワークフローでは、github.event コンテキストの次のプロパティが変更内容を説明します。

  • github.event.status には、課題が変更後になったステータスが含まれています。
  • github.event.changes.status.from には以前の状態、または課題に以前の状態がなかった場合は null が含まれます。
  • github.event.issue.status には、ペイロードがビルドされたときの問題の状態が含まれます。 すべての issues アクティビティの種類のペイロードには、このプロパティが含まれます。

重要

issuesなしでtypesイベントを使用するワークフローも、status_changedに対して実行されます。 これらのワークフローは、問題の状態を変更するたびに実行され、問題が作成、クローズ、または再度開かれたときに余分な時間が実行されます。これは、 GitHub が status_changed だけでなく、 opened、 closed、または reopenedを送信するためです。 予期しない実行を回避するには、ワークフローに必要なアクティビティの種類を一覧表示します。

プレビュー中に、ワークフロー ファイルを検証するエディター (GitHubのワークフロー エディターなど) は、status_changedを無効なアクティビティの種類として報告する場合があります。 このエラーは無視できます。

ステータス ID によって一致するものと、カテゴリ内のすべてのステータスに一致するワークフローの例については、ワークフローをトリガーするイベント を参照してください。

ペイロードの例

次の抜粋は、変更を説明するstatus_changedペイロードのプロパティを示しています。 完全なペイロードには、完全な issue、 repository、 sender オブジェクト、およびその他のプロパティも含まれます。

課題の作成

誰かがステータスを選択せずにIssueを作成すると、Issueはバックログのステータスになります。 changes.status.from は nullであり、 changes には state や state_reasonは含まれません。

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 2,
      "name": "Backlog",
      "category": "backlog"
    }
  },
  "status": {
    "id": 2,
    "name": "Backlog",
    "category": "backlog"
  },
  "changes": {
    "status": {
      "from": null
    }
  }
}

同じカテゴリの状態に変更する

進行中からレビュー中に問題を移動しても、状態またはそのカテゴリは変更されないため、 changes には statusのみが含まれます。

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "open",
    "state_reason": null,
    "status": {
      "id": 8,
      "name": "In review",
      "category": "started"
    }
  },
  "status": {
    "id": 8,
    "name": "In review",
    "category": "started"
  },
  "changes": {
    "status": {
      "from": {
        "id": 4,
        "name": "In progress",
        "category": "started"
      }
    }
  }
}

ステータスを変更して課題を終了する

[レビュー中] から [完了] に問題を移動すると、問題が終了します。 changes.state.from は openであり、 changes.state_reason.from は以前に問題に状態の理由がなかったため、 null です。 GitHub また、この変更の closed 配信も送信します。

{
  "action": "status_changed",
  "issue": {
    "number": 1347,
    "state": "closed",
    "state_reason": "completed",
    "status": {
      "id": 5,
      "name": "Done",
      "category": "completed"
    }
  },
  "status": {
    "id": 5,
    "name": "Done",
    "category": "completed"
  },
  "changes": {
    "status": {
      "from": {
        "id": 8,
        "name": "In review",
        "category": "started"
      }
    },
    "state": {
      "from": "open"
    },
    "state_reason": {
      "from": null
    }
  }
}