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

添付コンテンツについて

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": {
    "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も必要になります。

application/vnd.github.corsair-preview+json

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コメント内のリンクの下に、新しい添付コンテンツが表示されます。

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

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

application/vnd.github.corsair-preview+json

例:

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アプリケーションを作成するには、以下のステップに従ってください。

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

2. 作成したプロジェクトを開き、 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
   

3. このコードを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()'
       })
     })
   }
   

4. GitHub Appをローカルで動作させます。 http://localhost:3000にアクセスして、Register GitHub Appボタンをクリックしてください。

   

5. テストリポジトリにアプリケーションをインストールしてください。

6. テストリポジトリでIssueを作成してください。

7. オープンしたIssueにapp.ymlファイルで設定したURLを含むコメントを追加してください。

8. Issueのコメントを見ると、以下のように更新されています。