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

添付コンテンツを使うと、GitHub Appは登録されたドメインにリンクするURLに対し、GitHub内でより多くの情報を提供できます。 GitHubは、アプリケーションから提供された情報を、IssueやPull Requestのボディやコメント内のURLの下に表示します。

ノート: 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 idrepository full_nameフィールドを使います。 GitHub Appのインストールとして認証を受けるために、installation idも必要になります。

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

application/vnd.github.corsair-preview+json

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

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

curl -X POST \
  https://api.github.com/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は、プレビュー期間に予告なく変更されることがあります。 プレビューの機能は、実稼働環境での利用はサポートされていません。 問題があった場合には、GitHub Supportにお問い合わせください。

例:

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

  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ボタンをクリックしてください。

    Probot GitHub App の登録

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

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

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

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

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

このドキュメントは役立ちましたか?

プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?