How-To's Tutorials

如何将 Qodana 集成到 TeamCity 中 

有诸多令人信服的理由让您使用 TeamCity 作为 CI 服务器。得益于其开箱即用的功能、智能测试管理能力，以及面向企业的出色可扩缩性，TeamCity 提供了强大且可靠的 CI 解决方案。但如果您真正希望提升合规性、改善代码质量和安全性，可以将它与 Qodana 配合使用。 

集成 Qodana 的静态代码分析功能可以显著提升代码库质量，并帮助您在 CI/CD 管道中实施更好的标准。借助专用 Qodana 构建运行程序提供的内置支持，将代码质量检查直接嵌入开发工作流正变得越来越简单。

在这篇博文中，我们将探讨 Qodana 与 TeamCity 如何互补，以及如何开始集成过程。

将 Qodana 引入 TeamCity

Qodana 作为 TeamCity 内的构建运行程序提供，因此可以轻松将静态分析集成到现有的构建中。首先，需要确保项目使用 Qodana 支持的语言（例如 Java、Kotlin、PHP、Python、JavaScript、TypeScript、Go 或 C#）进行构建。 

Qodana 与各种 IDE 和任何 CI 管道兼容，包括所有 JetBrains IDE（例如 IntelliJ IDEA 和 Rider）、VS Code 和 Visual Studio，以及 Jenkins 和 .NET 等平台。您可以在此处查找 Qodana linter 列表。

如果您运行的是自己的 TeamCity 代理，应确保 Docker 已安装并且可访问。对于采用 JetBrains 托管代理的 TeamCity Cloud 用户，Docker 已设置完毕。

值得注意的是，Qodana 目前不支持 TeamCity 中基于 Windows 的构建代理。

在构建管道中配置 Qodana

在 TeamCity 中设置 Qodana 非常简单。

虽然推荐采用且最简单的方式是将 `qodana.yaml` 配置文件直接放在仓库中，但 Qodana 也支持通过 TeamCity 的命令行运行程序进行动态配置。这种方式对于边缘用例非常实用，例如团队需要根据项目类型、团队偏好或环境动态定制检查的情况。

话虽如此，对于大多数团队而言，使用带有版本控制的 `qodana.yaml` 文件能够确保各个构建之间的一致性、清晰性和可追溯性。

要了解如何在 TeamCity 中设置动态配置，请查看我们对此查询的回复。 

更青睐可视化程度更高的方式？ 在 TeamCity UI 中探索 Qodana 的代码覆盖率报告 – 无需编写任何脚本。

第 1 步 ：在 TeamCity 中，进入构建的配置页面，并添加新的构建步骤。 

第 2 步：选择 Qodana 构建运行程序，然后展开高级选项，以自定义其行为。

第 3 步：定义您要使用的 linter、指定版本，并指向默认或自定义检查配置文件。如果您使用的是 Qodana Cloud，还可以在此阶段添加项目令牌。对于商业 linter，此操作为必选项，对于社区 linter，则为可选项。

buildType {
    steps {
        qodana {
            name = "Qodana analysis"
            linter = jvm {
                version = Qodana.JVMVersion.LATEST
            }
            inspectionProfile = embedded {
                name = "qodana.starter"
            }
            cloudToken = "%qodana.cloud.token%"
            additionalQodanaArguments = "--baseline qodana.sarif.json"
        }
    }
}

可选步骤：为实现更精细的控制，您可以配置独一无二的报告 ID、工作目录，或 Qodana 报告是否应在 TeamCity 中的 Tests（测试）标签页下显示等信息。还支持高级参数，例如 Docker 实参或附加 Qodana CLI 选项。

如需更详细的说明以及每个步骤的功能的更多信息，请查看文档。 

在 TeamCity 中配置 Qodana

质量门和基准比较

质量门这类工具可以在代码不满足特定要求或标记的问题过于严重或问题数量过多的情况下阻止代码合并到 main 分支中。如果未达到质量门条件，Qodana 会使用退出码 255 终止，进而导致 CI/CD 工作流或管道失败。 

利用 Qodana，可以轻松设置质量门，当问题数量超出设定的阈值时，使构建失败。Qodana 还支持基准功能，这样，您可以将当前分析结果与之前的状态进行对比。此功能可以帮助识别新问题，而不会在每次分析时都标记相同的问题。

这两个功能均可以在 Qodana 运行程序中通过简单的命令行实参进行配置。您可以通过多种方式进行设置。例如，可以创建一个质量门，先考虑问题数量，然后再决定是否允许代码合并（`qodana.yaml` 中提供更灵活的设置）：

failureConditions:
  severityThresholds:
    any: 10 # Total problems
    critical: 5 # Critical and other severities
    high: 5
    moderate: 10
    low: 20
    info: 20

质量门与基准功能相结合，可以帮助团队规避危机，同时避免遗留问题造成的不必要干扰。

设置质量门

通过脚本进行自定义配置

如果项目需要自定义检查配置文件或特定的排除项，您可以使用 `qodana.yaml` 文件。您可以将此文件包含在仓库中，或在 TeamCity 中使用脚本实时生成该文件。

查看配置文档

在 TeamCity 或 Qodana Cloud 中查看结果

构建运行后，Qodana 会提供灵活的选项来查看结果。您可以直接在 TeamCity 的 Qodana 标签页中访问详细的分析结果，从而轻松发现问题并查看其他构建诊断。

您也可以在 Qodana Cloud 中探索结果，其中提供的基于 Web 的仪表板包含协作工具、历史记录跟踪，并集成了问题跟踪器。

支持拉取请求和分支分析

Qodana 也能很好地适用于拉取请求工作流。拉取请求分析的目的是检查拉取请求或合并请求中的代码更改，从而检测出由该特定更改引入或修正的问题。

Qodana 会将当前分支与目标分支（如 `main` 或 `develop`）进行对比，然后只高亮显示更改过的文件或代码行中的问题。

通过在 TeamCity 中配置 VCS 触发器，您可以在将合并请求或特定分支集成到主代码库之前对其进行分析。这为每一次代码审查增添了一层关键的质量保障。

随后，基准会通过将当前分析结果与之前的“无问题”状态进行对比，跟踪一段时间内出现的新问题。

您可以生成基准文件，在后续运行中，Qodana 会将当前问题与该基准进行对比。仅会将新问题（基准中不存在的问题）报告为问题。

这些方式可以结合使用，以改善质量门和实施。

TeamCity Cloud 和 Qodana Cloud 可以打造质量更高的软件产品

将 Qodana 集成到 TeamCity 管道为提高代码库健康度奠定了坚实的基础。通过在构建过程中自动运行静态分析，您可以降低 bug 被遗漏的概率，并且可以作为团队使用 Qodana 实施质量规范。

TeamCity 与 Qodana 相互补充，TeamCity 用于管理构建，Qodana 则确保代码整洁，让您引以为傲。两者可以预防后续问题，共同提供自动化、可扩缩的 CI/CD 方案，从一开始就内置代码质量保障。

常见问题解答

如何使用 Qodana 分析 .NET 项目？

要分析 .NET 项目，您可以使用 `qodana-dotnet` Docker 镜像或基于 Rider 的原生解决方案。还可以通过 `qodana-cdnet` 镜像获取 Community Edition，但为了获得更强大的功能，建议使用付费许可证的试用版本。

为什么 TeamCity 经常与 Qodana 而不是其他分析器搭配使用？

TeamCity 和 Qodana 均由 JetBrains 打造，这意味着两者深度集成，竞争对手无法轻易再现这一点。 

如果我遇到问题，可以在哪里获取帮助？ 

您可以访问此 TeamCity 支持页面，或发送电子邮件联系 Qodana 支持。

还没有 TeamCity？ 点击下方按钮下载。
如需详细了解 Qodana 的方案和定价，请参阅此处。 

下载 TeamCity

特别感谢 Irina Khromova 和 Pavel Sher 对这篇博文的贡献。

 

本博文英文原作者：