github-community-projects/issue-metrics

# Issue Metrics Action [](https://github.com/github-community-projects/issue-metrics/actions/workflows/github-code-scanning/codeql) [](https://github.com/github-community-projects/issue-metrics/actions/workflows/docker-image.yml) [](https://github.com/github-community-projects/issue-metrics/actions/workflows/python-package.yml) [](https://scorecard.dev/viewer/?uri=github.com/github-community-projects/issue-metrics) [](https://www.bestpractices.dev/projects/9501) 这是一个 GitHub Action，用于搜索仓库中的 issue/pull request/discussion，测量多项指标，并生成 GitHub issue 形式的报告。 可以使用搜索查询来过滤要搜索的 issue/pull request/discussion。 此 Action 由 GitHub OSPO 开发，最初用于内部用途，现将其开源以期能为您提供便利。 欢迎在此仓库中创建 issue 来询问其使用方法。 ## 可用指标 | 指标 | 描述 | | --------------------------------- | ------------------------------------------------------------------------------------------ | | 首次响应时间 | 从创建到首次评论或审查的持续时间。\* | | 首次审查时间 (仅限 PR) | 从创建到首次提交审查的持续时间。\* | | 关闭时间 | 从创建到关闭的时间段。\* | | 回答时间 (仅限 Discussion) | 从创建到获得回答的时间。 | | 标签停留时间 | 从应用标签到移除标签的持续时间，需要设置 `LABELS_TO_MEASURE` 环境变量。 | | 草稿停留时间 (仅限 PR) | 从创建到 PR 被标记为“准备审查”的持续时间。 | \*对于 pull request，这些指标不包括 PR 处于草稿状态的时间。 \*对于 issue 和 pull request，不包括 issue/pull request 作者的评论以及机器人的评论。 要查找搜索查询的语法，请查看有关[搜索 issue 和 pull request](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) 或 [搜索 discussion](https://docs.github.com/en/search-github/searching-on-github/searching-discussions) 的文档。 ## 报告示例 此 Action 的输出是 GitHub issue 形式的报告。 下面是一个此类 GitHub issue 的示例。  ## 快速开始 在您的仓库中创建一个包含以下内容的工作流文件（例如：`.github/workflows/issue-metrics.yml`）： **注意**：`repo:owner/repo` 是您想要测量指标的目标仓库 ``` name: Monthly issue metrics on: workflow_dispatch: schedule: - cron: "3 2 1 * *" permissions: contents: read jobs: build: name: issue metrics runs-on: ubuntu-latest permissions: issues: write pull-requests: read steps: - name: Get dates for last month shell: bash run: | # Calculate the first day of the previous month first_day=$(date -d "last month" +%Y-%m-01) # Calculate the last day of the previous month last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d) #Set an environment variable with the date range echo "$first_day..$last_day" echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV" - name: Run issue-metrics tool uses: github-community-projects/issue-metrics@v4 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} SEARCH_QUERY: 'repo:owner/repo is:issue created:${{ env.last_month }} -reason:"not planned"' - name: Create issue uses: peter-evans/create-issue-from-file@v5 with: title: Monthly issue metrics report token: ${{ secrets.GITHUB_TOKEN }} content-filepath: ./issue_metrics.md ``` ## 示例用例 - 作为维护者，我希望查看我所维护仓库中 issue 和 pull request 的指标，以确保我对它们给予了足够的关注。 - 作为仓库的首席响应者，我希望确保用户能在合理的时间内得到我的回复。 - 作为 OSPO，我希望查看有多少开源仓库请求处于打开/关闭状态，以及完成开源流程所需时间的指标。 - 作为产品开发团队，我希望查看 pull request 审查所花费的时间指标，以便我们在回顾会议上分析这些数据。 ## 支持 如果您在使用此项目时需要支持或有任何疑问，请[在此仓库中创建一个 issue](https://github.com/github-community-projects/issue-metrics/issues)。直接向 GitHub 员工或支持团队提出的请求将被重定向到这里以创建 issue。GitHub 的 SLA 和支持/服务合同不适用于此仓库。 ### OSPO GitHub Actions 整体 关于我们 GitHub Actions 的所有反馈（作为一个整体），应通过[github-ospo 仓库上的 issue](https://github.com/github/github-ospo/issues/new) 进行沟通。 ## 作为 GitHub Action 使用 1. 创建一个仓库来托管此 GitHub Action，或选择一个现有仓库。如果与您想要测量指标的仓库相同，这是最简单的。 2. 从[示例目录](./docs/example-workflows.md) 中为您的用例选择最合适的工作流文件。 3. 将该示例复制到您的仓库（从第 1 步）中，并放入 GitHub Actions 的正确目录：`.github/workflows/` 目录下，文件扩展名为 `.yml`（例如：`.github/workflows/issue-metrics.yml`） 4. 使用您的信息编辑示例工作流中的值（`SEARCH_QUERY`、`assignees`）。有关如何配置搜索查询的更多信息，请参阅 [SEARCH_QUERY](./docs/search-query.md) 部分。 5. 如果您要在非工作流文件所在的其他仓库上运行指标，请更新 `GH_TOKEN` 的值。 - 通过创建一个具有读取仓库和写入 issue 权限的 [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) 来执行此操作。 - 然后获取您刚刚创建的 API token 的值，并[创建一个仓库 secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets)，其中 secret 名称为 `GH_TOKEN`，值为该 API token。 - 最后更新工作流文件以使用该仓库 secret，将 `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` 更改为 `GH_TOKEN: ${{ secrets.GH_TOKEN }}`。该 secret 的名称其实可以是任何名字。它只需要在您创建 secret 名称时与您在工作流文件中引用它时保持一致即可。 - 有关验证您的 token 对仓库访问权限的帮助，请参阅 [docs 目录](docs/verify-token-access-to-repository.md) 6. 如果您希望包含指标的生成 issue 出现在运行工作流文件所在仓库以外的其他仓库中，请使用您自己存储为仓库 secret 的 GitHub API token 更新 `token: ${{ secrets.GITHUB_TOKEN }}` 这一行。 - 此过程与上述步骤中描述的相同。有关创建 secret 的更多信息，请参阅[GitHub 文档中有关加密 secret 的安全指南](https://docs.github.com/en/actions/security-guides/encrypted-secrets)。 7. 将工作流文件提交到默认分支（通常是 `master` 或 `main`） 8. 等待 Action 根据 `schedule` 条目触发，或者按照[文档](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) 中的说明手动触发工作流。 ### 配置 以下是允许的配置选项： #### 身份验证 此 Action 可配置为使用 GitHub App Installation 或 Personal Access Token (PAT) 进行身份验证。如果提供了所有配置选项，则 GitHub App Installation 配置具有优先权。您可以选择以下方法之一进行身份验证： ##### GitHub App 安装 | 字段 | 必填 | 默认值 | 描述 | | ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GH_APP_ID` | True | `""` | GitHub Application ID。有关更多详细信息，请参阅[文档](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)。 | | `GH_APP_INSTALLATION_ID` | True | `""` | GitHub Application Installation ID。有关更多详细信息，请参阅[文档](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)。 | | `GH_APP_PRIVATE_KEY` | True | `""` | GitHub Application Private Key。有关更多详细信息，请参阅[文档](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)。 | | `GITHUB_APP_ENTERPRISE_ONLY` | False | false | 如果您的应用程序是在 GHE 中创建并与 GHE 通信，请将此输入设置为 `true`。 | ##### Personal Access Token (PAT) | 字段 | 必填 | 默认值 | 描述 | | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | `GH_TOKEN` | True | `""` | 用于扫描仓库的 GitHub Token。必须对您有兴趣扫描的所有仓库具有读取权限。 | #### 其他配置选项 | 字段 | 必填 | 默认值 | 描述 | | ----------------------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GH_ENTERPRISE_URL` | False | `""` | 用于身份验证的 GitHub Enterprise 实例 URL，替代 github.com | | `HIDE_ASSIGNEE` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示指派人。 | | `HIDE_AUTHOR` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示作者。 | | `HIDE_ITEMS_CLOSED_COUNT` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示已关闭项目的数量指标。 | | `HIDE_LABEL_METRICS` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示标签停留时间指标。 | | `HIDE_TIME_TO_ANSWER` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示 discussion 的回答时间。 | | `HIDE_TIME_TO_CLOSE` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示关闭时间。 | | `HIDE_TIME_TO_FIRST_RESPONSE` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示首次响应时间。 | | `HIDE_TIME_TO_FIRST_REVIEW` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示首次审查时间。 | | `HIDE_STATUS` | False | True | 如果设置为 `true`，将不会显示状态列 | | `HIDE_CREATED_AT` | False | True | 如果设置为 `true`，生成的 Markdown 文件中将不会显示创建时间戳。 | | `HIDE_PR_STATISTICS` | False | True | 如果设置为 `true`，生成的 Markdown 文件中将不会显示 PR 评论统计信息（平均值、中位数、第 90 百分位数以及各 PR 的评论数）。 | | `HIDE_ITEMS_LIST` | False | False | 如果设置为 `true`，生成的 Markdown 文件中将不会显示单个 pull request、issue 和 discussion 的独立项目列表表格。仅显示汇总指标。 | | `DRAFT_PR_TRACKING` | False | False | 如果设置为 `true`，草稿 PR 将作为新列包含在指标和汇总统计中。 | | `IGNORE_USERS` | False | False | 计算指标时要忽略的以逗号分隔的用户列表。（例如：`IGNORE_USERS: 'user1,user2'`）。要忽略机器人，请在用户名后附加 `[bot]`（例如：`IGNORE_USERS: 'github-actions[bot]'`）。此列表中的用户其创建的 issue 和 pull request 也将从 Markdown 表格中移除。 | | `ENABLE_MENTOR_COUNT` | False | False | 如果设置为 'TRUE'，计算用户在 discussion、issue 和 PR 上留下的评论数，并显示活跃导师的数量 | | `MIN_MENTOR_COMMENTS` | False | 10 | 计为导师的最低评论数 | | `MAX_COMMENTS_EVAL` | False | 20 | 评估导师统计信息的每个话题的最大评论数 | | `HEAVILY_INVOLVED_CUTOFF` | False | 3 | 超过此截断值后，导师在某个 issue 中的评论将不再计入其总分 | | `LABELS_TO_MEASURE` | False | `""` | 以逗号分隔的标签列表，用于测量应用该标签的时间长度。如果未提供，则不会测量标签的持续时间。目前不适用于 discussion。 | | `NON_MENTIONING_LINKS` | False | False | 如果设置为 `true`，将使用非提及 GitHub 链接，以避免从源仓库链接到生成的 issue。将使用 `https://www.github.com` 格式的链接。 | | `OUTPUT_FILE` | False | `issue_metrics.md` 或 `issue_metrics.json` | 输出文件名。 | | `REPORT_TITLE` | False | `"Issue Metrics"` | 显示在报告 issue 上的标题。 | | `SEARCH_QUERY` | True | `""` | 用于过滤 issue/PR 的查询，必须包含 `repo:`、`org:`、`owner:` 或 `user:` 条目。对于 discussion，请在查询中包含 `type:discussions`。 | | `GROUP_BY` | False | `""` | 按指定字段对报告中的项目进行分组。支持的值：`author`、`assignee`。设置后，项目将按所选字段分组到不同的部分中。 | | `SORT_BY` | False | `""` | 按指定字段对报告中的项目进行排序。支持的值：`time_to_close`、`time_to_first_response`、`time_to_first_review`、`time_to_answer`、`time_in_draft`、`created_at`。设置后，项目将按所选指标进行排序。 | | `SORT_ORDER` | False | `asc` | 项目的排序顺序。支持的值：`asc`（升序）、`desc`（降序）。仅在设置了 `SORT_BY` 时适用 | ## 更多文档 - [示例工作流](./docs/example-workflows.md) - [测量标签停留时间](./docs/measure-time.md) - [分配团队而非个人](./docs/assign-team-instead-of-individual.md) - [使用 JSON 输出而非 Markdown 输出的示例](./docs/example-using-json-instead-markdown-output.md) - [配置 `SEARCH_QUERY`](./docs/search-query.md) - [不使用 Docker 的本地使用方法](./docs/local-usage-without-docker.md) - [使用 GitHub App Installation 进行身份验证](./docs/authenticating-with-github-app-installation.md) - [处理大型 issue_metrics.md 文件](./docs/dealing-with-large-issue-metrics.md) ### 开发设置 - 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/) - 克隆此仓库并进入 `issue-metrics` - 安装依赖项 `uv sync` - 运行测试 `make test` - 运行 linter `make lint` ## 许可证 [MIT](LICENSE) ## 更多 OSPO 工具 正在为您的开源项目办公室 (OSPO) 寻找更多资源？请查看 [`github-ospo`](https://github.com/github/github-ospo) 仓库，其中包含旨在满足您需求的各种工具。

标签：GitHub Action, Linux 内核安全, Python, 无后门, 研发度量, 社区运营, 请求拦截, 逆向工具, 项目管理