JetBrains/qodana-action

# Qodana Scan [](https://www.producthunt.com/posts/jetbrains-qodana) [][jb:confluence-on-gh] [][jb:discussions] [][jb:twitter] **Qodana** 是一个代码质量监控工具，能够识别并提供针对 Bug、安全漏洞、重复代码和各种瑕疵的修复建议。 **目录** - Qodana Scan - [用法](#usage) - [配置](#configuration) - [问题追踪器](#issue-tracker) ## 用法 [Qodana Scan GitHub action](https://github.com/marketplace/actions/qodana-scan) 允许你在 GitHub 仓库上运行 Qodana。 ### 基础配置 要配置 Qodana Scan，请保存包含以下工作流配置的 `.github/workflows/code_quality.yml` 文件： ``` name: Qodana on: workflow_dispatch: pull_request: push: branches: - main - 'releases/*' jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2026.1 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }} # read the steps about it below ``` 要在构建配置中设置 `QODANA_TOKEN` 环境变量： 1. 在 GitHub UI 中，创建 `QODANA_TOKEN` [加密密码](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)，并将[项目令牌](https://www.jetbrains.com/help/qodana/cloud-projects.html#cloud-manage-projects)保存为其值。 2. 在 GitHub 工作流文件中，将 `QODANA_TOKEN` 变量添加到 `Qodana Scan` 步骤的 `env` 部分： 使用此工作流，Qodana 将在主分支、发布分支以及指向你仓库的 Pull Request 上运行。 注意：如果 Qodana 在 Pull Request 模式下工作（报告仅在该 Pull Request 中出现的问题），在 checkout 时必须设置 `fetch-depth: 0`。 我们建议你为 Qodana 使用单独的工作流文件，因为[不同的作业是并行运行的](https://help.github.com/en/actions/getting-started-with-github-actions/core-concepts-for-github-actions#job)  ### 应用快速修复 要让 Qodana 自动修复发现的问题并将更改推送到你的仓库，你需要： 1. 选择要应用的修复类型 - [在你的仓库根目录下的 `qodana.yaml` 文件中指定 `fixesStrategy`](https://www.jetbrains.com/help/qodana/qodana-yaml.html) - 或者设置 action 的 `args` 属性以指定要使用的快速修复策略：`--apply-fixes` 或 `--cleanup` 2. 将 `push-fixes` 属性设置为： - `pull-request`：创建一个包含修复的新分支，并向原始分支创建一个 Pull Request - 或 `branch`：将修复推送到原始分支。同时，将 `pr-mode` 设置为 `false`：目前，此模式不支持应用修复。 3. 为作业设置正确的权限（`contents: write`、`pull-requests: write`、`checks: write`） - 如果你为 `push-fixes` 属性使用 `pull-request` 值：[**允许 GitHub Actions 创建和批准 Pull Request**](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests) 配置示例： ``` - name: Qodana Scan uses: JetBrains/qodana-action@v2026.1 with: pr-mode: false args: --apply-fixes push-fixes: pull-request env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` 如果你想在同一个作业中执行不同的 `git` 操作，可以禁用 `push-fixes` 并手动执行所需的操作：

💡完整脚本示例

``` name: Qodana on: workflow_dispatch: pull_request: push: branches: - master - 'releases/*' jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2026.1 with: args: --cleanup - run: | git config user.name github-actions git config user.email github-actions@github.com git checkout -b quick-fixes-$GITHUB_RUN_ID git add -- . ':!.idea' git commit -m "I fixed some issues" git push origin quick-fixes-$GITHUB_RUN_ID gh pr create --repo $GITHUB_REPOSITORY --base $GITHUB_REF_NAME --head quick-fixes-$GITHUB_RUN_ID --title "Pull requests" --body "I fixed some issues" env: GH_TOKEN: ${{ github.token }} ```

### GitHub 代码扫描 你可以使用 Qodana 为你的项目设置 [GitHub 代码扫描](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)。为此，请将这些行添加到 `code_quality.yml` 工作流文件中，紧接在 Qodana Scan 的[基础配置](#basic-configuration)之下： ``` - uses: github/codeql-action/upload-sarif@v2 with: sarif_file: ${{ runner.temp }}/qodana/results/qodana.sarif.json ``` 此示例调用 `codeql-action` 将 SARIF 格式的 Qodana 报告上传到 GitHub，并使用 `sarif_file` 键指定报告文件。 ### Pull Request 质量门禁 如果 Qodana 质量门禁失败，你可以强制 GitHub 阻止合并 Pull Request。为此，请按照以下描述创建一个[分支保护规则](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule)： 1. 创建一个新的或打开一个现有的、调用了 Qodana Scan action 的 GitHub 工作流。 2. 将工作流设置为在目标为 `main` 分支的 `pull_request` 事件上运行。 ``` on: pull_request: branches: - main ``` 你可以在此处指定你的分支，而不是 `main`。 3. 为 Qodana action 的 `fail-threshold` 选项设置问题数量（整数）。 4. 在你的仓库名称下，点击 **Settings**。 5. 在左侧菜单中，点击 **Branches**。 6. 在分支保护规则部分，点击 **Add rule**。 7. 在 **Branch name pattern** 中添加 `main`。 8. 选择 **Require status checks to pass before merging**。 9. 搜索 `Qodana` 状态检查，然后勾选它。 10. 点击 **Create**。 ### 质量门禁与基线 你可以结合使用[质量门禁](https://www.jetbrains.com/help/qodana/quality-gate.html)和[基线](https://www.jetbrains.com/help/qodana/qodana-baseline.html)功能来管理你的技术债务，仅报告新问题，并阻止包含过多问题的 Pull Request。 按照以下步骤为你的项目建立基线： 1. 在你的项目上[本地](https://www.jetbrains.com/help/qodana/getting-started.html#Analyze+a+project+locally)运行 Qodana： ``` cd project qodana scan --show-report ``` 2. 在 `http://localhost:8080/` 打开你的报告，[将检测到的问题](https://www.jetbrains.com/help/qodana/ui-overview.html#Technical+debt)添加到基线，并下载 `qodana.sarif.json` 文件。 3. 将 `qodana.sarif.json` 文件上传到你在 GitHub 上的项目根文件夹中。 4. 将 `--baseline,qodana.sarif.json` 参数追加到 `code_quality.yml` 文件中 Qodana Scan action 配置的 `args` 参数中： ``` - name: Qodana Scan uses: JetBrains/qodana-action@main with: args: --baseline,qodana.sarif.json ``` 如果你想更新基线，需要再次重复这些步骤。 从此开始，GitHub 将仅针对未作为新问题添加到基线中的问题生成警报。 要在基线的基础上建立质量门禁，请将以下内容添加到 `code_quality.yml` 中，紧跟在 `baseline-path` 行之后： ``` fail-threshold: ``` 基于此，你将能够检测到 Pull Request 中超出基线的仅有新问题。同时，**新**问题超过 `fail-threshold` 限制的 Pull Request 将被阻止，并且工作流将失败。 ### 获取 Qodana 徽章 你可以在你的仓库中设置 Qodana 工作流徽章，为此，请按照以下步骤操作： 1. 导航到你之前配置的工作流运行。 2. 在工作流页面上，选择 **Create status badge**。 3. 将 Markdown 文本复制到你的仓库 README 文件中。 ## 配置 大多数情况下，除了 `args` 之外你不需要其他选项：如果你在一个工作流中配置多个 Qodana Scan 作业，所有其他选项才会派上用场。 使用 [`with`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith) 来定义任何 action 参数： ``` with: args: --baseline,qodana.sarif.json cache-default-branch-only: true ``` | 名称 | 描述 | 默认值 | |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------| | `args` | 额外的 [Qodana CLI `scan` 命令](https://github.com/jetbrains/qodana-cli#scan) 参数，用逗号 (`,`) 分隔参数，例如 `-i,frontend,--print-problems`。可选。 | - | | `results-dir` | 存储分析结果的目录。可选。 | `${{ runner.temp }}/qodana/results` | | `upload-result` | 将 Qodana 结果（SARIF、其他 artifacts、日志）作为 artifact 上传到作业。可选。 | `false` | | `artifact-name` | 指定 Qodana 结果 artifact 名称，用于结果上传。可选。 | `qodana-report` | | `cache-dir` | 存储 Qodana 缓存的目录。可选。 | `${{ runner.temp }}/qodana/caches` | | `use-caches` | 在 Qodana 运行中使用 [GitHub 缓存](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)。可选。 | `true` | | `primary-cache-key` | 设置[主缓存键](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key)。可选。 | `qodana-2026.1-${{ github.ref }}-${{ github.sha }}` | | `additional-cache-key` | 设置[附加缓存键](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key)。可选。 | `qodana-2026.1-${{ github.ref }}` | | `cache-default-branch-only` | 仅为默认分支上传缓存。可选。 | `false` | | `use-annotations` | 使用标注在 GitHub 用户界面中标记结果。可选。 | `true` | | `pr-mode` | 仅分析 Pull Request 中更改的文件。可选。 | `true` | | `post-pr-comment` | 将包含 Qodana 结果摘要的评论发布到 Pull Request。可选。 | `true` | | `github-token` | 用于访问仓库的 GitHub token：发布标注、评论。可选。 | `${{ github.token }}` | | `push-fixes` | 将 Qodana 修复推送到仓库，可以是 `none`、`branch`（推送到当前分支）或 `pull-request`。可选。 | `none` | ## 问题追踪器 所有与 Qodana 相关的问题、功能请求和支持均在 [YouTrack][youtrack] 上处理。 如果你想提交新问题，请使用链接 [YouTrack | New Issue][youtrack-new-issue]。

标签：Azure, CircleCI, CMS安全, DevSecOps, GitHub Actions, Go, Gradle, JavaScript, JetBrains, Kotlin, OpenVAS, PHP, Python, Qodana, Ruby工具, TypeScript, 上游代理, 代码安全, 代码审查, 代码重复检测, 后台面板检测, 安全专业人员, 安全插件, 弱口令爆破, 技术债, 数据管道, 无后门, 漏洞枚举, 漏洞测试, 自动化审查, 自动笔记, 自定义脚本, 请求拦截, 软件工程, 静态代码扫描, 静态应用安全测试 (SAST)