ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2021-03-02. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの改善、新機能のためには、最新バージョンのGitHub Enterpriseにアップグレードしてください。 アップグレードに関する支援については、GitHub Enterprise supportに連絡してください。

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

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

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

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を使わなければなりません。

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

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

  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)
         // "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
    
  4. GitHub Appをローカルで動作させますhttp://localhost:3000にアクセスして、Register GitHub Appボタンをクリックしてください。

    Probot GitHub App の登録

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

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

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

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

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