Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-10-12. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

使用内容附件

内容附件允许 GitHub 应用程序在 GitHub 中为链接到注册域的 URL 提供更多信息。 GitHub 可渲染应用程序在正文或者议题或拉取请求注释中的 URL 下提供的信息。

注意: Content Attachments API 目前处于公共 beta 版,仅用于 GitHub 应用。 在此期间,功能和要求可能会随时更改。

关于内容附件

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。

添� 到议题的 URL

步骤 3. � 的应用将收到包含操作 createdcontent_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 idrepository full_name 字段来通过 REST API 创建内容附件。 还需要使用 installation id 作为 GitHub 应用安装进行身份验证。

注意:若要在预览期间访问 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 应用进行身份验证”。

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

附� 到议题引用的内容

在 GraphQL 中使用内容附件

我们在 content_reference Webhook 事件中提供 node_id,以便� 可以在 GraphQL API 中引用 createContentAttachment 突变。

注意:若要在预览期间访问 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 的详细信息,请参阅“使用全局 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 应用”按钮:

    注册 Probot GitHub 应用程序

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

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

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

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

    附� 到议题引用的内容