如何配置GitLab CI/CD仅在新增flake8违规时触发流水线失败

针对大型遗留Python代码库，直接因flake8违规终止CI流水线会阻塞开发进度，我们可以配置流水线只检查新增/变更代码中的违规——允许历史遗留问题存在，但严格阻止代码质量进一步恶化。以下是几种可行方案：

方案1：使用flake8原生--diff参数 #

flake8支持通过--diff参数仅分析Git版本差异中的代码变更行，完全忽略历史遗留的违规。

GitLab CI配置示例：

flake8-new-violations:
  stage: code-quality
  image: python:3.10
  before_script:
    - pip install flake8
    - git fetch origin main  # 拉取基准分支（如main）的最新代码
  script:
    # 对比当前分支与main分支的差异，仅检查变更代码中的flake8违规
    - flake8 --diff HEAD origin/main
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'  # 仅在MR触发时运行

该命令只会扫描两个版本间的代码变更行，只有这些行中出现的违规才会导致流水线失败，历史遗留问题不会产生影响。

方案2：用diff-quality精准统计新增违规 #

diff-quality是专门对比代码质量报告的工具，可明确统计新增违规数，而非仅检查变更行。

配置步骤：

1. 在CI环境安装依赖：

pip install diff-quality flake8

2. GitLab CI配置示例：

diff-quality-check:
  stage: code-quality
  image: python:3.10
  before_script:
    - pip install diff-quality flake8
    - git fetch origin main
  script:
    # 切换到基准分支，生成基准违规报告
    - git checkout origin/main
    - flake8 --format=pylint > baseline.txt
    # 切回当前分支，生成当前违规报告
    - git checkout $CI_COMMIT_SHA
    - flake8 --format=pylint > current.txt
    # 对比报告，仅当新增违规数>0时触发失败
    - diff-quality --violations=flake8 baseline.txt current.txt --fail-on-new
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

--fail-on-new参数会让工具在检测到新增违规时返回非零状态，直接终止流水线。

方案3：仅检查变更的Python文件（需注意局限性） #

如果只需扫描本次提交中修改过的Python文件，可以用Git命令筛选目标文件后再执行flake8：

flake8-changed-files:
  stage: code-quality
  image: python:3.10
  before_script:
    - pip install flake8
    - git fetch origin main
  script:
    # 获取当前分支与main分支差异中的Python文件
    - CHANGED_PY_FILES=$(git diff --name-only origin/main HEAD | grep '\.py$')
    # 若存在变更文件，执行flake8检查
    - if [ -n "$CHANGED_PY_FILES" ]; then flake8 $CHANGED_PY_FILES; fi
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

⚠️ 注意：该方案会检查整个变更文件，而非仅变更行。如果文件中存在历史违规但本次未修改对应代码，flake8仍会报错。适合对代码质量要求稍宽松、仅需阻止新增文件或大幅修改文件出现违规的场景。

关键注意事项 #

• 统一flake8版本与配置：确保基准分支和当前分支使用完全一致的flake8版本、.flake8配置文件，避免因规则差异导致误判。
• 聚焦Merge Request：建议仅在MR阶段触发检查，避免对所有分支推送都执行，减少不必要的CI资源消耗。
• 逐步清理遗留违规：可定期针对单个模块修复历史违规，更新基准报告或调整检查范围，逐步提升整体代码质量。

内容的提问来源于stack exchange，提问作者GabCaz