Note: The Content Attachments API is currently in public beta and only available for use with GitHub Apps. Features and requirements may change at any time during this period.
添付コンテンツについて
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を使わなければなりません。
ステップ3。アプリケーションはcreated
アクション付きでcontent_reference
webhookを受信します。
{
"action": "created",
"content_reference": {
"id": 17,
"node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
"reference": "errors.ai"
},
"repository": {...},
"sender": {...},
"installation": {
"id": 371641,
"node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
}
}
ステップ4。アプリケーションはREST APIを使って添付コンテンツを作成するためにcontent_reference
id
を使います。 GitHub Appのインストールとして認証を受けるために、installation
id
も必要になります。
Note: To access the Content Attachments API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.corsair-preview+json
Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your site administrator.
body
パラメータにはMarkdownが含まれていることがあります。
<pre><code class="hljs language-shell">curl -X POST \
https://api.github.com/content_references/1512/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()"
}'</code></pre>
インストールトークンの作成に関する詳しい情報については「GitHub Appとして認証する」を参照してください。
ステップ5。 Pull RequestもしくはIssueコメント内のリンクの下に、新しい添付コンテンツが表示されます。
GraphQLでの添付コンテンツの利用
content_reference
webhookイベント中でnode_id
を提供しているので、GraphQL APIのcreateContentAttachment
ミューテーションを参照できます。
Note: To access the Content Attachments API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.corsair-preview+json
Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact 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" "https://api.github.com/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アプリケーションを作成するには、以下のステップに従ってください。
-
作成したプロジェクトを開き、
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) // "Create a content reference" RESTエンドポイントを呼ぶ await context.github.request({ method: 'POST', headers: { accept: 'application/vnd.github.corsair-preview+json' }, url: `/content_references/${context.payload.content_reference.id}/attachments`, // パラメータ 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()' }) }) }body
-
GitHub Appをローカルで動作させます。
http://localhost:3000
にアクセスして、Register GitHub Appボタンをクリックしてください。 -
テストリポジトリにアプリケーションをインストールしてください。
-
テストリポジトリでIssueを作成してください。
-
オープンしたIssueに
app.yml
ファイルで設定したURLを含むコメントを追加してください。 -
Issueのコメントを見ると、以下のように更新されています。