使用内容附件

关于内容附件

GitHub 应用可以注册将触发 content_reference 事件的域。 当有人在正文或者问题或拉取请求的注释中包含链接到注册域的 URL 时，应用会收到 content_reference Webhook。 您可以使用内容附件直观地为添� 到议题或拉取请求的 URL 提供更多的上下文或数据。 URL 必须是完全限定的 URL，以 http:// 或 https:// 开头。 Markdown 链接中的 URL 将被忽略，不会触发 content_reference 事件。

在使用 Content Attachments API 之前，您需要为 GitHub 应用程序配置内容引用：

• 为应用提供对“内容引用”的 Read & write 权限。
• 配置“内容引用”权限时，注册最多 5 个有效且可公开访问的域。 配置内容引用域时不要使用 IP 地址。 您可以注册域名 (example.com) 或子域 (subdomain.example.com)。
• 让应用程序订阅“内容引用”事件。

将应用程序安装到仓库中后，仓库中包含注册域 URL 的议题或拉取请求注释将生成内容引用事件。 应用程序必须在发布内容引用 URL 后六小时内创建内容附件。

内容附件不会追溯更新 URL。 只有在您� �据上述要求配置了应用程序，并且有人在其仓库中安装应用程序之后，它才会更新添� 到议题或拉取请求中的 URL。

有关配置 GitHub 应用权限和事件订阅所需的步骤，请参阅创建 GitHub 应用或编辑 GitHub 应用的权限。

实现内容附件流程

内容附件流程向� 显示问题或拉取请求中的 URL、content_reference Webhook 事件以及使用额外信息更新问题或拉取请求所需调用的 REST API 终结点之间的关系：

步骤 1. 使用关于内容附件中的指南设置应用。 � 也可以� �据 Probot 应用示例开始使用内容附件。

步骤 2. 将已注册的域的 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. 应用使用 content_reference id 和 repository full_name 字段来通过 REST API 创建内容附件。 还需要使用 installation id 作为 GitHub 应用安装进行身份验证。

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 应用进行身份验证”。

步骤 5. 在拉取请求或问题注释中，� 将看到新的内容附件显示在链接下：

在 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 的详细信息，请参阅“使用全局 Node ID”。

使用 Probot 和 GitHub 应用程序清单的示例

要快速设置可使用 Content Attachments API 的 GitHub 应用，� 可以使用 Probot。 要了解 Probot 如何使用 GitHub 应用清单，请参阅从清单创建 GitHub 应用。

要创建 Probot 应用程序，请按照以下步骤操作：

1. 生成新的 GitHub 应用。

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. 将此代� �添� 到 index.js 文件以处理 content_reference 事件并调用 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: `/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 应用。 导航到 http://localhost:3000，并单击“注册 GitHub 应用”按钮：

   

5. 在测试仓库中安装应用程序。

6. 在测试仓库中创建议题。

7. 将注释添� 到� 打开的问题，其中包括� 在 app.yml 文件中配置的 URL。

8. 查看议题注释，您将看到如下所示的更新：