添付コンテンツを使用する

ノート: Content Attachments APIは現在パブリックベータであり、GitHub Appsと合わせてのみ利用できます。この期間中、機能や要件はいつでも変更されることがあります。

添付コンテンツについて

GitHub Appは、content_referenceイベントをトリガーするドメインを登録できます。 Issueまたはプルリクエストの、ボディまたはコメントに、登録されたドメインにリンクするURLが含まれている� �合、アプリケーションはcontent_reference webhookを受け取ります。添付コンテンツを使用して、Issueまたはプルリクエストに追� したURLについてのコンテキストやデータを視覚的に追� できます。 URLは、http://またはhttps://から始まる、完全修飾URLである必要があります。 Markdownリンクの一部であるURLは無視され、content_referenceイベントをトリガーしません。

Content Attachments APIを使用する前に、以下を行ってGitHub Appのコンテンツ参照を設定する必要があります。

アプリケーションに、[Content references] に対するRead & write権限を付与します。
[Content references] 権限を設定する際に、一般にアクセス可能なドメインを5つまで登録します。コンテンツ参照ドメインを設定する際は、IPアドレスは使用しないでく� さい。ドメイン名 (example.com) またはサブドメイン (subdomain.example.com) を登録できます。
アプリケーションを [Content reference] イベントにサブスクライブします。

アプリケーションがリポジトリにインストールされると、登録されたドメインへのURLが含まれるIssueまたはプルリクエストのコメントでは、コンテンツ参照イベントが生成されます。アプリケーションは、コンテンツ参照URLがポストされてから6時間以内に添付コンテンツを作成しなければなりません。

添付コンテンツが、URLを遡って更新することはありません。上記でまとめた要件に従ってアプリケーションを設定した後に、ユーザがリポジトリにアプリケーションをインストールしてから、Issueまたはプルリクエストに追� したURLに対してのみ機能します。

GitHub App の権限やイベントのサブスクリプションを設定するために必要なステップに関する詳しい情� �については、「<GitHub App を作成する」または「GitHub App の権限を編集する」を参照してく� さい。

添付コンテンツフローを実装する

添付コンテンツのフローは、IssueもしくはPull Request中のURL、content_reference webhookイベント、追� 情� �でIssueもしくはPull Requestを更新するために呼ぶ必要があるREST APIエンドポイント間の関係を示します。

ステップ 1. 添付コンテンツについてに記載されているガイドラインに従ってアプリケーションを設定します。添付コンテンツを使い始めるには、Probotアプリケーションのサンプルを使うこともできます。

ステップ2。IssueもしくはPull Requestに登録したドメインのURLを追� します。 http://もしくはhttps://で始まる完全修飾URLを使わなければなりません。

Issueに追� されたURL

ステップ3。アプリケーションはcreatedアクション付きでcontent_reference webhookを受信します。

{
  "action": "created",
  "content_reference": {
    "id": 17,
    "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
    "reference": "errors.ai"
  },
  "repository": {
    "full_name": "Codertocat/Hello-World",
  },
  "sender": {...},
  "installation": {
    "id": 371641,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
  }
}

ステップ4。アプリケーションはREST APIを使って添付コンテンツを作成するためにcontent_reference idとrepository full_nameフィールドを使います。 GitHub Appのインストールとして認証を受けるために、installation idも必要になります。

ノート: プレビュー期間中にContent Attachments APIにアクセスするには、カスタ� のメディアタイプをAcceptヘッダに渡さなければなりません。

application/vnd.github.corsair-preview+json

警告: このAPIは、プレビュー期間に予告なく変更されることがあります。プレビューの機能は、実稼働環境での利用はサポートされていません。問題があった� �合には、your site administratorにお問い合わせく� さい。

bodyパラメータにはMarkdownが含まれていることがあります。

curl -X POST \
  http(s)://[hostname]/api/v3/repos/Codertocat/Hello-World/content_references/17/attachments \
  -H 'Accept: application/vnd.github.corsair-preview+json' \
  -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
  -d '{
    "title": "[A-1234] Error found in core/models.py file",
    "body": "You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
}'

インストールトークンの作成に関する詳しい情� �については「GitHub Appとして認証する」を参照してく� さい。

ステップ5。 Pull RequestもしくはIssueコメント内のリンクの下に、新しい添付コンテンツが表示されます。

Issueのリファレンスに添付されたコンテンツ

GraphQLでの添付コンテンツの利用

content_reference webhookイベント中でnode_idを提供しているので、GraphQL APIのcreateContentAttachmentミューテーションを参照できます。

ノート: プレビュー期間中にContent Attachments APIにアクセスするには、カスタ� のメディアタイプをAcceptヘッダに渡さなければなりません。

application/vnd.github.corsair-preview+json

警告: このAPIは、プレビュー期間に予告なく変更されることがあります。プレビューの機能は、実稼働環境での利用はサポートされていません。問題があった� �合には、your site administratorにお問い合わせく� さい。

例:

mutation {
  createContentAttachment(input: {
    contentReferenceId: "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1",
    title: "[A-1234] Error found in core/models.py file",
    body:"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
  }) {
    contentAttachment {
      ... on ContentAttachment {
        id
        title
        body
      }
    }
  }
}

cURLの例:

curl -X "POST" "http(s)://[hostname]/api/v3/graphql" \
     -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
     -H 'Accept: application/vnd.github.corsair-preview+json' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "query": "mutation {\\n  createContentAttachment(input:{contentReferenceId: \\"MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1\\", title:\\"[A-1234] Error found in core/models.py file\\", body:\\"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n\self.save()\\"}) {\\n    contentAttachment {\\n      id,\\n      title,\\n      body\\n    }\\n  }\\n}"
}'

node_idの詳しい情� �については「グローバルノードIDの利用」を参照してく� さい。

ProbotとGitHub Appマニフェストの利用例

Content Attachments APIを使用できるGitHub Appを手早くセットアップするには、Probotが利用できます。 ProbotがどのようにGitHub Appのマニフェストを使用するかを学ぶには、「マニフェストからのGitHub Appの作成」を参照してく� さい。

Probotアプリケーションを作成するには、以下のステップに従ってく� さい。

新しい GitHub App を作成します。

作成したプロジェクトを開き、 app.yml ファイルの設定をカスタマイズします。 content_referenceイベントをサブスクライブし、content_referencesの書き込み権限を有効化してく� さい。

 default_events:
   - content_reference
 # GitHub Appが必要とする権限セット。 このオブジェクトのフォーマットは、
 # キーの権限名（たとえばissues）と値のためのアクセスの
 # 種類（たとえばwrite）を使います。
 # 取り得る値は `read`、`write`、`none`
 default_permissions:
   content_references: write

 content_references:
   - type: domain
     value: errors.ai
   - type: domain
     value: example.org

このコードをindex.js ファイルに追� して、content_referenceを処理してREST APIを呼ぶようにします。

module.exports = app => {
  // ここにコードを書く
  app.log('Yay, the app was loaded!')
   app.on('content_reference.created', async context => {
    console.log('Content reference created!', context.payload)
     // Call the "Create a content reference" REST endpoint
    await context.github.request({
      method: 'POST',
      headers: { accept: 'application/vnd.github.corsair-preview+json' },
      url: `/repos/${context.payload.repository.full_name}/content_references/${context.payload.content_reference.id}/attachments`,
      // Parameters
      title: '[A-1234] Error found in core/models.py file',
      body: 'You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\nself.save()'
    })
  })
}

GitHub Appをローカルで動作させます。 http://localhost:3000にアクセスして、Register GitHub Appボタンをクリックしてく� さい。
テストリポジトリにアプリケーションをインストールしてく� さい。
テストリポジトリでIssueを作成してく� さい。
オープンしたIssueにapp.ymlファイルで設定したURLを含むコメントを追� してく� さい。
Issueのコメントを見ると、以下のように更新されています。

添付コンテンツを使用する

ここには以下の内容があります:

添付コンテンツについて

添付コンテンツフローを実装する

GraphQLでの添付コンテンツの利用

ProbotとGitHub Appマニフェストの利用例