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

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

Using content attachments

Content attachments allow a GitHub App to provide more information in GitHub for URLs that link to registered domains. GitHub renders the information provided by the app under the URL in the body or comment of an issue or pull request.

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

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.

About content attachments

A GitHub App can register domains that will trigger content_reference events. When someone includes a URL that links to a registered domain in the body or comment of an issue or pull request, the app receives the content_reference webhook. You can use content attachments to visually provide more context or data for the URL added to an issue or pull request. The URL must be a fully-qualified URL, starting with either http:// or https://. URLs that are part of a markdown link are ignored and don't trigger the content_reference event.

Before you can use the Content Attachments API, you'll need to configure content references for your GitHub App:

  • Give your app Read & write permissions for "Content references."
  • Register up to 5 valid, publicly accessible domains when configuring the "Content references" permission. Do not use IP addresses when configuring content reference domains. You can register a domain name (example.com) or a subdomain (subdomain.example.com).
  • Subscribe your app to the "Content reference" event.

Once your app is installed on a repository, issue or pull request comments in the repository that contain URLs for your registered domains will generate a content reference event. アプリケーションは、コンテンツ参照URLがポストされてから6時間以内に添付コンテンツを作成しなければなりません。

Content attachments will not retroactively update URLs. It only works for URLs added to issues or pull requests after you configure the app using the requirements outlined above and then someone installs the app on their repository.

See "Creating a GitHub App" or "Editing a GitHub App's permissions" for the steps needed to configure GitHub App permissions and event subscriptions.

Implementing the content attachment flow

The content attachment flow shows you the relationship between the URL in the issue or pull request, the content_reference webhook event, and the REST API endpoint you need to call to update the issue or pull request with additional information:

Step 1. Set up your app using the guidelines outlined in About content attachments. You can also use the Probot App example to get started with content attachments.

Step 2. Add the URL for the domain you registered to an issue or pull request. You must use a fully qualified URL that starts with http:// or https://.

URL added to an issue

Step 3. Your app will receive the content_reference webhook with the action created.

{
  "action": "created",
  "content_reference": {
    "id": 17,
    "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
    "reference": "errors.ai"
  },
  "repository": {...},
  "sender": {...},
  "installation": {
    "id": 371641,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
  }
}

Step 4. The app uses the content_reference id, to Create a content attachment using the REST API. You'll also need the installation id to authenticate as a GitHub App installation.

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.

The body parameter can contain 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>

For more information about creating an installation token, see "Authenticating as a GitHub App."

Step 5. You'll see the new content attachment appear under the link in a pull request or issue comment:

Content attached to a reference in an issue

Using content attachments in GraphQL

We provide the node_id in the content_reference webhook event so you can refer to the createContentAttachment mutation in the GraphQL API.

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
      }
    }
  }
}

Example 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}"
}'

For more information on node_id, see "Using Global Node IDs."

Example using Probot and GitHub App Manifests

To quickly setup a GitHub App that can use the Content Attachments API, you can use Probot. See "Creating GitHub Apps from a manifest" to learn how Probot uses GitHub App Manifests.

To create a Probot App, follow these steps:

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

  2. 作成したプロジェクトを開き、 app.yml ファイルの設定をカスタマイズします。 Subscribe to the content_reference event and enable content_references write permissions:

    
     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. Add this code to the index.js file to handle content_reference events and call the REST API:

    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: `/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. Run the GitHub App locally. Navigate to localhost:3000, and click the Register GitHub App button:

    Probot GitHub App の登録

  5. Install the app on a test repository.

  6. Create an issue in your test repository.

  7. Add a comment to the issue you opened that includes the URL you configured in the app.yml file.

  8. Take a look at the issue comment and you'll see an update that looks like this:

    Content attached to a reference in an issue