Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となります: 2022-09-28. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください

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

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

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

  1. 新しい GitHub App を生成します

  2. 作成したプロジェクトを開き、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
    
  3. 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()'
        })
      })
    }
    
  4. GitHub App をローカルで実行しますhttp://localhost:3000 に移動し、 [GitHub App を登録] ボタンをクリックします。

    Probot GitHub App の登録

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

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

  7. オープンした issue に app.yml ファイルで設定した URL を含むコメントを追加します。

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

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