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

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

添付コンテンツについて

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

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

"コンテンツ参照" のアクセス許可をアプリ 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 は、プレビュー期間中は事前の通知なしに変更されることがあります。プレビューの機能は、実稼働環境での利用はサポートされていません。問題があった� �合には、サイト管理者にお問い合わせく� さい。

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での添付コンテンツの利用

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

注: プレビュー期間中に Content Attachments API にアクセスするには、Accept ヘッダーにカスタ� メディアの種類を指定する必要があります。

application/vnd.github.corsair-preview+json

警告: この API は、プレビュー期間中は事前の通知なしに変更されることがあります。プレビューの機能は、実稼働環境での利用はサポートされていません。問題があった� �合には、サイト管理者にお問い合わせく� さい。

次に例を示します。

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 アプリマニフェスト使用する方法については、「マニフェストから GitHub App を作成する」を参照してく� さい。

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

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

作成したプロジェクトを開き、app.yml ファイルの設定をカスタマイズします。 content_reference イベントを登録し、content_references 書き込みアクセス許可を有効にします。

 default_events:
   - content_reference
 # The set of permissions needed by the GitHub App. The format of the object uses
 # the permission name for the key (for example, issues) and the access type for
 # the value (for example, write).
 # Valid values are `read`, `write`, and `none`
 default_permissions:
   content_references: write

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

content_reference イベントを処理して REST API を呼び出すには、次のコードを index.js ファイルに追� します。

module.exports = app => {
  // Your code here
  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 に移動し、 [GitHub App を登録] ボタンをクリックします。
テストリポジトリにアプリケーションをインストールしてく� さい。
テストリポジトリでIssueを作成してく� さい。
オープンした issue に app.yml ファイルで設定した URL を含むコメントを追� します。
Issueのコメントを見ると、以下のように更新されています。

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

この記事では、次の� �目が扱われます。

添付コンテンツについて

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

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

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