« Elastic Dropbox 连接器参考 Elastic Gmail 连接器参考 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›使用 Elastic 连接器摄取内容 ›连接器参考

Elastic GitHub 连接器参考

编辑

Elastic GitHub 连接器参考

编辑

Elastic GitHub 连接器 是一个用于 GitHub 的连接器。此连接器使用 Elastic 连接器框架，用 Python 编写。

查看此连接器的 源代码（分支 8.17，与 Elastic 8.17 兼容）。

选择您的连接器参考

您是在 Elastic Cloud 上使用托管连接器还是自托管连接器？根据您的部署方法展开文档。

Elastic 托管连接器参考

编辑
查看 Elastic 托管连接器 参考
可用性和先决条件
编辑

此连接器从 Elastic 版本 8.11.0 开始作为托管连接器提供。

要以原生方式在 Elastic Cloud 中使用此连接器，请满足所有 托管连接器要求。

创建 GitHub 连接器
编辑

使用 UI

编辑

要创建新的 GitHub 连接器

  1. 在 Kibana UI 中，从主菜单导航到 搜索 → 内容 → 连接器 页面，或使用全局搜索字段。
  2. 按照说明创建新的原生 GitHub 连接器。

有关其他操作，请参阅Kibana 中的连接器 UI。

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API 来创建新的原生 GitHub 连接器。

例如

resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
    is_native=True,
)
print(resp)
const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
  is_native: true,
});
console.log(response);
PUT _connector/my-github-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from GitHub",
  "service_type": "github",
  "is_native": true
}
您还需要为连接器创建一个 API 密钥以供使用。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 以编程方式生成 API 密钥。

要为连接器创建 API 密钥

  1. 运行以下命令，替换指示的值。请注意响应中的 id 和 encoded 返回值

    resp = client.security.create_api_key(
    name="my-connector-api-key",
    role_descriptors={
        "my-connector-connector-role": {
            "cluster": [
                "monitor",
                "manage_connector"
            ],
            "indices": [
                {
                    "names": [
                        "my-index_name",
                        ".search-acl-filter-my-index_name",
                        ".elastic-connectors*"
                    ],
                    "privileges": [
                        "all"
                    ],
                    "allow_restricted_indices": False
                }
            ]
        }
    },
)
print(resp)
    const response = await client.security.createApiKey({
  name: "my-connector-api-key",
  role_descriptors: {
    "my-connector-connector-role": {
      cluster: ["monitor", "manage_connector"],
      indices: [
        {
          names: [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*",
          ],
          privileges: ["all"],
          allow_restricted_indices: false,
        },
      ],
    },
  },
});
console.log(response);
    POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

  2. 使用 encoded 值存储连接器密钥，并记下此响应中的 id 返回值

    resp = client.connector.secret_post(
    body={
        "value": "encoded_api_key"
    },
)
print(resp)
    const response = await client.connector.secretPost({
  body: {
    value: "encoded_api_key",
  },
});
console.log(response);
    POST _connector/_secret
{
  "value": "encoded_api_key"
}

  3. 使用 API 密钥 id 和连接器密钥 id 更新连接器

    resp = client.connector.update_api_key_id(
    connector_id="my_connector_id>",
    api_key_id="API key_id",
    api_key_secret_id="secret_id",
)
print(resp)
    const response = await client.connector.updateApiKeyId({
  connector_id: "my_connector_id>",
  api_key_id: "API key_id",
  api_key_secret_id: "secret_id",
});
console.log(response);
    PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器 API 的详细信息，请参阅Elasticsearch API 文档。

用法
编辑

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅Kibana 中的连接器 UI。

GitHub 个人访问令牌
编辑

配置 GitHub 个人访问令牌以从 GitHub 获取数据。

按照以下步骤生成 GitHub 个人访问令牌

  • 转到 GitHub 设置 → 开发人员设置 → 个人访问令牌 → 令牌（经典）。
  • 选择 生成新令牌。

  • 添加备注并选择以下范围

    • repo
    • user
    • read:org
  • 选择 生成令牌 并复制令牌。
GitHub 应用程序
编辑

配置 GitHub 应用程序以从 GitHub 获取数据。

按照以下步骤创建 GitHub 应用程序

  • 转到 GitHub 设置 → 开发人员设置 → GitHub 应用程序。
  • 选择 新建 GitHub 应用程序。
  • 添加名称和主页 URL，取消选中 Webhook 下的 活动。
  • 在 权限 下，为 提交状态、内容、问题、元数据 和 拉取请求 选择 只读，在 存储库权限 下，为 成员 选择 只读，在 组织权限 下。
  • 为 可以在哪里安装此 GitHub 应用程序？ 选择 任何帐户。
  • 单击 创建 GitHub 应用程序。
  • 向下滚动到 私钥 部分，然后单击 生成私钥。
  • 单击左上角的 安装应用程序，选择要安装 GitHub 应用程序的组织/个人帐户，然后单击 安装。
  • 您可以选择将其安装在所有存储库或选定的存储库上，然后单击 安装。
兼容性
编辑

GitHub 和 GitHub Enterprise 均受支持。

配置
编辑

以下配置字段是必需的

数据源
在 GitHub 云或 GitHub 服务器之间切换。
服务器 URL
GitHub 服务器实例的 URL。（仅限 GitHub 服务器）
身份验证方法
用于验证 GitHub 实例的方法。在 个人访问令牌 和 GitHub 应用程序 之间切换。
令牌
用于验证 GitHub 实例的 GitHub 个人访问令牌。此字段仅适用于 个人访问令牌 身份验证方法。
存储库类型
在 组织 和 其他 之间切换。请注意，文档级安全性 (DLS) 仅适用于 组织 存储库。
组织名称
从中获取数据的组织名称。仅当 身份验证方法 设置为 个人访问令牌 且 存储库类型 设置为 组织 时，此字段才可用。
应用程序 ID
GitHub 应用程序的应用程序 ID。仅当 身份验证方法 设置为 GitHub 应用程序 时，此字段才可用。
应用程序私钥
为 GitHub 应用程序生成的私钥。仅当 身份验证方法 设置为 GitHub 应用程序 时，此字段才可用。
存储库列表

要从中获取 GitHub 实例数据的以逗号分隔的存储库列表。如果该值为 *，则连接器将从配置用户的帐户中存在的所有存储库中获取数据。

默认值为 *。

示例

  • elasticsearch、elastic/kibana
  • *

存储库所有权

如果省略了 "OWNER/REPO" 存储库参数的 "OWNER/" 部分，则默认设置为进行身份验证的用户的名称。

在 此处提供的示例中

  • 同步的 elasticsearch 存储库将是 <OWNER>/elasticsearch 存储库
  • 同步的 kibana 存储库将是 Elastic 拥有的存储库

当选择 GitHub 应用程序 作为 身份验证方法 时，必须提供 "OWNER/REPO" 存储库参数的 "OWNER/" 部分。

此字段可以通过高级同步规则绕过。

启用 SSL
为 GitHub 实例启用 SSL。
SSL 证书

GitHub 实例的 SSL 证书。示例

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----
启用文档级安全性
切换以启用文档级安全性 (DLS)。启用后，完全同步将获取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。当 存储库类型 设置为 组织 时，DLS 才可用。
文档和同步
编辑

连接器同步以下对象和实体

  • 存储库
  • 拉取请求
  • 问题
  • 文件和文件夹

仅摄取以下文件扩展名

  • .markdown
  • .md
  • .rst
  • 不会提取大于 10 MB 的文件的内容。（自托管连接器可以使用自托管本地提取服务来处理更大的二进制文件。）
  • 权限不会同步。索引到 Elastic 部署中的所有文档对所有有权访问该 Elasticsearch 索引的用户可见。
同步类型
编辑

默认情况下，所有连接器都支持完全同步。

此连接器还支持增量同步。

同步规则
编辑

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。有关更多信息，请阅读同步规则的类型。

高级同步规则
编辑

高级同步规则生效需要完全同步。

以下部分描述了此连接器的 高级同步规则。高级同步规则通过特定于源的 DSL JSON 代码片段定义。

以下部分提供了此连接器的高级同步规则示例。

根据通过 branch 键配置的分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "branch": "sync-rules-feature"
    }
  }
]

基于问题键索引与错误相关的问题查询的文档

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug"
    }
  }
]

基于 PR 键索引与打开的 PR 相关的 PR 查询的文档

[
  {
    "repository": "repo_name",
    "filter": {
      "pr": "is:open"
    }
  }
]

基于查询和分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug",
      "pr": "is:open",
      "branch": "sync-rules-feature"
    }
  }
]

给定规则提取的所有文档都会被索引，无论该文档是否已被先前的规则索引。这可能会导致文档重复，但日志中索引的文档计数会有所不同。请检查 Elasticsearch 索引以获取实际的文档计数。

重叠的高级规则

[
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-20"
    },
    "repository": "repo_name"
  },
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-15"
    },
    "repository": "repo_name"
  }
]

如果选择 GitHub 应用程序 作为身份验证方法，则必须提供“OWNER/”部分的“OWNER/REPO”存储库参数。

内容提取
编辑

请参阅 内容提取。

已知问题
编辑

目前，此连接器没有已知问题。有关所有连接器的已知问题列表，请参阅 已知问题。

故障排除
编辑

请参阅 故障排除。

安全性
编辑

请参阅 安全性。

自管理连接器

编辑
查看 自管理连接器 参考
可用性和先决条件
编辑

此连接器作为自管理 自管理连接器 提供。

此自管理连接器与 Elastic 版本 8.10.0+ 兼容。

要使用此连接器，请满足所有 自管理连接器要求。

创建 GitHub 连接器
编辑

使用 UI

编辑

要创建新的 GitHub 连接器

  1. 在 Kibana UI 中，从主菜单导航到 搜索 → 内容 → 连接器 页面，或使用全局搜索字段。
  2. 按照说明创建新的 GitHub 自管理连接器。

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API 来创建新的自管理 GitHub 自管理连接器。

例如

resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
)
print(resp)
const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
});
console.log(response);
PUT _connector/my-github-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from GitHub",
  "service_type": "github"
}
您还需要为连接器创建一个 API 密钥以供使用。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 以编程方式生成 API 密钥。

要为连接器创建 API 密钥

  1. 运行以下命令，并在指示的位置替换值。请注意响应中 encoded 的返回值

    resp = client.security.create_api_key(
    name="connector_name-connector-api-key",
    role_descriptors={
        "connector_name-connector-role": {
            "cluster": [
                "monitor",
                "manage_connector"
            ],
            "indices": [
                {
                    "names": [
                        "index_name",
                        ".search-acl-filter-index_name",
                        ".elastic-connectors*"
                    ],
                    "privileges": [
                        "all"
                    ],
                    "allow_restricted_indices": False
                }
            ]
        }
    },
)
print(resp)
    const response = await client.security.createApiKey({
  name: "connector_name-connector-api-key",
  role_descriptors: {
    "connector_name-connector-role": {
      cluster: ["monitor", "manage_connector"],
      indices: [
        {
          names: [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*",
          ],
          privileges: ["all"],
          allow_restricted_indices: false,
        },
      ],
    },
  },
});
console.log(response);
    POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}
  2. 使用 API 密钥 encoded 值更新您的 config.yml 文件。

有关所有可用连接器 API 的详细信息，请参阅Elasticsearch API 文档。

用法
编辑

要将此连接器用作 自管理连接器，请参阅 自管理连接器。有关其他使用操作，请参阅 Kibana 中的连接器 UI。

GitHub 个人访问令牌
编辑

配置 GitHub 个人访问令牌以从 GitHub 获取数据。

按照以下步骤生成 GitHub 访问令牌

  • 转到 GitHub 设置 → 开发人员设置 → 个人访问令牌 → 令牌（经典）。
  • 选择 生成新令牌。

  • 添加备注并选择以下范围

    • repo
    • user
    • read:org
  • 选择 生成令牌 并复制令牌。
GitHub 应用程序
编辑

配置 GitHub 应用程序以从 GitHub 获取数据。

按照以下步骤创建 GitHub 应用程序

  • 转到 GitHub 设置 → 开发人员设置 → GitHub 应用程序。
  • 选择 新建 GitHub 应用程序。
  • 添加名称和主页 URL，取消选中 Webhook 下的 活动。
  • 在 权限 下，为 提交状态、内容、问题、元数据 和 拉取请求 选择 只读，在 存储库权限 下，为 成员 选择 只读，在 组织权限 下。
  • 为 可以在哪里安装此 GitHub 应用程序？ 选择 任何帐户。
  • 单击 创建 GitHub 应用程序。
  • 向下滚动到 私钥 部分，然后单击 生成私钥。
  • 单击左上角的 安装应用程序，选择要安装 GitHub 应用程序的组织/个人帐户，然后单击 安装。
  • 您可以选择将其安装在所有存储库或选定的存储库上，然后单击 安装。
兼容性
编辑

GitHub 和 GitHub Enterprise 均受支持。

配置
编辑

当使用 构建连接器 工作流程时，这些字段最初将使用在 连接器源代码 中设置的默认配置。这些设置在 get_default_configuration 函数定义中。

这些可配置字段将在 Kibana UI 中使用各自的 标签 呈现。连接后，您将能够在 Kibana 中更新这些值。

以下配置字段是必需的

data_source
GitHub 云或 GitHub 服务器。
host
GitHub 服务器实例的 URL。（仅限 GitHub 服务器）
auth_method
用于验证 GitHub 实例的方法。在 个人访问令牌 和 GitHub 应用程序 之间切换。
token
用于验证 GitHub 实例的 GitHub 个人访问令牌。此字段仅适用于 个人访问令牌 身份验证方法。
repo_type
在 组织 和 其他 之间切换。请注意，文档级安全性 (DLS) 仅适用于 组织 存储库。
org_name
从中获取数据的组织名称。仅当 身份验证方法 设置为 个人访问令牌 且 存储库类型 设置为 组织 时，此字段才可用。
app_id
GitHub 应用程序的应用程序 ID。仅当 身份验证方法 设置为 GitHub 应用程序 时，此字段才可用。
private_key
为 GitHub 应用程序生成的私钥。仅当 身份验证方法 设置为 GitHub 应用程序 时，此字段才可用。
repositories

要从中获取 GitHub 实例数据的以逗号分隔的存储库列表。如果该值为 *，则连接器将从配置用户的帐户中存在的所有存储库中获取数据。

默认值为 *。

示例

  • elasticsearch、elastic/kibana
  • *

存储库所有权

如果省略了 "OWNER/REPO" 存储库参数的 "OWNER/" 部分，则默认设置为进行身份验证的用户的名称。

在 此处提供的示例中

  • 同步的 elasticsearch 存储库将是 <OWNER>/elasticsearch
  • 同步的 kibana 存储库将是 Elastic 拥有的存储库

当选择 GitHub 应用程序 作为 身份验证方法 时，必须提供 "OWNER/REPO" 存储库参数的 "OWNER/" 部分。

此字段可以通过高级同步规则绕过。

ssl_enabled
是否启用 SSL 验证。默认值为 False。
ssl_ca

SSL 证书的内容。注意：如果 ssl_enabled 为 False，则将忽略此字段中的值。示例证书

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----
use_document_level_security
切换以启用文档级安全性 (DLS)。启用后，完全同步将获取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。当 存储库类型 设置为 组织 时，DLS 才可用。
retry_count
对 GitHub 的请求失败后的重试尝试次数。默认值为 3。
use_text_extraction_service
需要单独部署 Elastic 文本提取服务。需要管道设置禁用文本提取。默认值为 False。
使用 Docker 部署
编辑

您可以使用 Docker 将 GitHub 连接器部署为自管理连接器。请按照以下说明操作。

步骤 1：下载示例配置文件

下载示例配置文件。您可以手动下载，也可以运行以下命令

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

如果您的目录名称不同，或者您想使用不同的配置文件名，请记住更新 --output 参数值。

步骤 2：更新您的自管理连接器的配置文件

使用以下设置更新配置文件，以匹配您的环境

  • elasticsearch.host
  • elasticsearch.api_key
  • connectors

如果您在 Docker 化的 Elasticsearch 和 Kibana 版本上运行连接器服务，则您的配置文件将如下所示

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: github
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

建议使用 elasticsearch.api_key 作为身份验证方法。但是，您也可以使用 elasticsearch.username 和 elasticsearch.password 对您的 Elasticsearch 实例进行身份验证。

注意：您可以通过简单地取消注释配置文件中的特定设置并修改其值来更改其他默认配置。

步骤 3：运行 Docker 镜像

使用以下命令运行带有连接器服务的 Docker 镜像

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.17.0.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

有关更多详细信息，请参阅 elastic/connectors 存储库中的 DOCKER.md。

在 官方注册表 中查找所有可用的 Docker 镜像。

我们还提供了一个使用 Docker Compose 的快速入门自管理选项，因此您可以一次启动所有必需的服务：Elasticsearch、Kibana 和连接器服务。有关更多信息，请参阅 elastic/connectors 存储库中的此 自述文件。

文档和同步
编辑

连接器同步以下对象和实体

  • 存储库
  • 拉取请求
  • 问题
  • 文件和文件夹

仅摄取以下文件扩展名

  • .markdown
  • .md
  • .rst
  • 不会提取大于 10 MB 的文件的内容。
  • 权限不会同步。索引到 Elastic 部署中的所有文档对所有有权访问该 Elasticsearch 索引的用户可见。
同步类型
编辑

默认情况下，所有连接器都支持完全同步。

此连接器还支持增量同步。

同步规则
编辑

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。有关更多信息，请阅读同步规则的类型。

高级同步规则
编辑

高级同步规则生效需要完全同步。

以下部分描述了此连接器的 高级同步规则。高级同步规则通过特定于源的 DSL JSON 代码片段定义。

以下部分提供了此连接器的高级同步规则示例。

基于通过分支键配置的分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "branch": "sync-rules-feature"
    }
  }
]

基于问题键索引与错误相关的问题查询的文档

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug"
    }
  }
]

基于 PR 键索引与打开的 PR 相关的 PR 查询的文档

[
  {
    "repository": "repo_name",
    "filter": {
      "pr": "is:open"
    }
  }
]

基于查询和分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug",
      "pr": "is:open",
      "branch": "sync-rules-feature"
    }
  }
]

给定规则提取的所有文档都会被索引，无论该文档是否已被先前的规则索引。这可能会导致文档重复，但日志中索引的文档计数会有所不同。请检查 Elasticsearch 索引以获取实际的文档计数。

重叠的高级规则

[
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-20"
    },
    "repository": "repo_name"
  },
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-15"
    },
    "repository": "repo_name"
  }
]

如果选择 GitHub 应用程序 作为身份验证方法，则必须提供“OWNER/”部分的“OWNER/REPO”存储库参数。

内容提取
编辑

请参阅 内容提取。

自管理连接器操作
编辑
端到端测试
编辑

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅 连接器测试。

要对 GitHub 连接器执行 E2E 测试，请运行以下命令

$ make ftest NAME=github

为了更快地测试，添加 DATA_SIZE=small 标志

make ftest NAME=github DATA_SIZE=small
已知问题
编辑

目前，此连接器没有已知问题。有关所有连接器的已知问题列表，请参阅 已知问题。

故障排除
编辑

请参阅 故障排除。

安全性
编辑

请参阅 安全性。

« Elastic Dropbox 连接器参考 Elastic Gmail 连接器参考 »