Làm Cùng Long.
← Quay lại Kho ghi chú
Automation & AI · 7 phút đọc ·

GitHub Code Quality API 2026: dùng findings và setup config để đưa code quality vào workflow

GitHub Code Quality API cho phép làm gì trong 2026, và nên nối nó vào workflow engineering như thế nào để findings thực sự dẫn tới hành động?

GitHub Code Quality API hiện có gì?

Theo GitHub Docs 2026, nhóm REST API này có hai lớp chính.

Lớp 1 — Findings

Có endpoint để:

  • liệt kê code quality findings của repository;
  • lấy chi tiết một finding;
  • lọc theo trạng thái như open hoặc dismissed;
  • đọc rule, severity, category, file path, line/column và message liên quan.

Ví dụ endpoint liệt kê findings:

GET /repos/{owner}/{repo}/code-quality/findings

Một finding có thể chứa những phần như:

  • rule ID;
  • title/description;
  • severity;
  • category như maintainability;
  • location trong file;
  • message giải thích vấn đề.

Lớp 2 — Setup configuration

Có endpoint để đọc và cập nhật cấu hình Code Quality:

GET   /repos/{owner}/{repo}/code-quality/setup
PATCH /repos/{owner}/{repo}/code-quality/setup

Tài liệu hiện cho phép cấu hình những field như:

  • state: configured hoặc not-configured;
  • runner_type: standard hoặc labeled;
  • runner_label nếu dùng labeled runner;
  • languages;
  • ai_findings_option: ví dụ on_push hoặc disabled.

1. Đừng biến Code Quality thành một score mới

Một hệ thống engineering rất dễ rơi vào bẫy “có metric thì tối ưu metric”.

Ví dụ:

  • số finding giảm;
  • warning giảm;
  • coverage tăng;
  • lint sạch;
  • build xanh.

Tất cả đều hữu ích, nhưng không cái nào tự động đồng nghĩa codebase tốt hơn cho người dùng và team.

Một finding chỉ thực sự có giá trị khi có workflow:

Finding
  ↓
Triage
  ↓
Có đáng sửa không?
  ↓
Owner
  ↓
Fix / dismiss có lý do
  ↓
PR + test
  ↓
Đo tác động / regression

Nếu API chỉ được dùng để kéo findings về dashboard rồi không ai chịu trách nhiệm, nó chỉ tạo thêm một nguồn cảnh báo.

2. Findings API phù hợp với bài toán nào?

Tạo dashboard theo repository hoặc team

Có thể tổng hợp:

  • số open findings;
  • severity/category;
  • repository;
  • file/module bị lặp finding;
  • tuổi của finding;
  • xu hướng mở/đóng theo thời gian.

Nhưng dashboard nên trả lời câu hỏi hành động, ví dụ:

  • module nào đang tích technical debt nhanh nhất?
  • finding nghiêm trọng nào chưa có owner?
  • rule nào tạo quá nhiều noise?
  • repository nào cần review cấu hình?

Tạo triage queue

API có thể cấp dữ liệu cho một workflow như:

GitHub Code Quality
        ↓
Fetch open findings
        ↓
Filter severity/category
        ↓
Map CODEOWNERS / team
        ↓
Create review queue
        ↓
Human triage

Điểm quan trọng là human triage. Không phải finding nào cũng đáng mở issue riêng.

Theo dõi remediation

Nếu team có baseline, có thể snapshot findings theo tuần/tháng để nhìn xu hướng thay vì chỉ trạng thái hiện tại.

3. Setup API giúp gì?

Với nhiều repository, cấu hình thủ công dễ lệch nhau.

Setup API phù hợp với governance:

  • repository nào đã bật Code Quality;
  • ngôn ngữ nào đang được phân tích;
  • runner setup có đúng chuẩn team không;
  • AI findings có bật không;
  • repository mới có được bootstrap theo policy chung không.

Ví dụ request cập nhật theo schema trong GitHub Docs:

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/code-quality/setup \
  -d '{
    "state":"configured",
    "languages":["javascript-typescript","python"]
  }'

Tài liệu GitHub hiện liệt kê các giá trị ngôn ngữ được hỗ trợ gồm:

  • csharp;
  • go;
  • java-kotlin;
  • javascript-typescript;
  • python;
  • ruby.

Vì API có thể thay đổi, những field này nên được kiểm tra lại từ docs trước khi viết automation production.

4. Quyền truy cập: phần dễ bị bỏ qua

Findings và setup không dùng cùng một permission.

Theo tài liệu hiện tại:

  • đọc findings cần quyền Code quality: read với fine-grained token;
  • đọc/cập nhật setup yêu cầu quyền repository Administration: write trong tài liệu endpoint tương ứng.

Điều này có hai ý nghĩa.

Không cấp token rộng hơn nhu cầu

Một dashboard chỉ đọc findings không cần quyền quản trị repository.

Tách workflow read và write

Nếu có automation cấu hình hàng loạt repository, nên tách nó khỏi pipeline chỉ đọc/monitoring để giảm blast radius.

Nguyên tắc:

read path rộng hơn, write path hẹp hơn và có approval.

5. Code Quality không thay thế lint, test hay security scanning

Các lớp giải quyết vấn đề khác nhau:

Linter

Ví dụ ESLint giúp enforce rule ở source code rất sớm, có thể chạy local trước commit.

Unit/integration test

Kiểm tra behavior mà static finding không thể suy ra đầy đủ.

Security scanning

Tập trung vào vulnerability, secret, dependency hoặc data flow tùy tool.

Code Quality findings

Là thêm một lớp signal về maintainability/code issue trong hệ sinh thái GitHub.

Một pipeline thực tế có thể là:

Local lint/typecheck
      ↓
PR
      ↓
Unit/integration tests
      ↓
Security checks
      ↓
Code quality findings
      ↓
Review + merge gate phù hợp

Không cần buộc mọi finding thành blocker. Severity và false positive cần được triage.

6. Đừng tự động tạo issue cho mọi finding

Một anti-pattern rất phổ biến của automation:

1 finding = 1 GitHub issue

Nếu repository có hàng trăm findings, backlog trở thành noise.

Tốt hơn là gom theo:

  • module;
  • rule;
  • owner;
  • severity;
  • sprint/remediation batch.

Ví dụ:

Rule A: 42 findings
  ↓
Review 5 mẫu
  ↓
Rule có signal tốt?
  ↓
Có → batch remediation
Không → tune/dismiss policy

Đây là cách tránh “automation tạo việc” thay vì giảm việc.

7. Một workflow tham khảo cho team nhỏ

Bước 1 — Baseline

Lấy danh sách open findings và lưu snapshot.

Bước 2 — Phân nhóm

Theo:

  • severity;
  • category;
  • path;
  • owner.

Bước 3 — Triage mẫu

Đọc thủ công một nhóm nhỏ để biết signal có đáng tin không.

Bước 4 — Chọn policy

Ví dụ:

  • finding mức nghiêm trọng cao → review bắt buộc;
  • maintainability mức thấp → gom backlog;
  • false positive → dismiss có lý do;
  • recurring rule → sửa pattern hoặc guideline.

Bước 5 — Đo xu hướng

Không chỉ nhìn “còn bao nhiêu”, mà nhìn:

  • findings mới/tuần;
  • median age;
  • tỷ lệ resolved;
  • module tái phát;
  • regression sau refactor.

8. Nếu tích hợp qua GitHub Actions, cần guardrail gì?

  • không hardcode PAT;
  • ưu tiên fine-grained token/GitHub App với permission tối thiểu;
  • write action cần approval nếu tác động config repository;
  • không log token hoặc response chứa dữ liệu nhạy cảm;
  • đặt timeout/retry có giới hạn;
  • xử lý 403, 404, 409, 422, 503 theo semantics của API;
  • dùng API version header;
  • không fail production deploy chỉ vì một dashboard sync bị lỗi nếu nó không phải quality gate chính.

9. Khi nào API này đáng dùng?

Đáng dùng nếu

  • có nhiều repository;
  • cần governance nhất quán;
  • muốn gom findings về dashboard/triage;
  • muốn kiểm tra drift của setup;
  • team đã có owner và review process.

Chưa cần nếu

  • repository nhỏ;
  • lint/test hiện tại đã đủ;
  • không ai có thời gian triage findings;
  • mục tiêu chỉ là “thêm AI vào CI”.

Trong trường hợp đó, thêm API không làm hệ thống tốt hơn.

10. Cách LongDigi áp dụng nguyên tắc này

LongDigi hiện có một bài toán gần giống ở content pipeline:

Content change
   ↓
Validator
   ↓
CI build
   ↓
PR
   ↓
Human/production gate

Bài học giống Code Quality: validator chỉ có giá trị khi signal được phân loại đúng.

Một bài thiếu cover không nên làm sập toàn website; nó nên bị quarantine. Nhưng lỗi schema, asset path hỏng hoặc marker nội bộ lọt public phải là hard fail.

Đó là tư duy “signal → severity → action” thay vì “mọi cảnh báo = stop”.

Kết luận

GitHub Code Quality API hữu ích ở vai trò automation layer cho findings và configuration.

Nó không tự tạo codebase tốt hơn, không thay thế test/lint/security và không nên trở thành một điểm số để team chạy theo.

Giá trị của code-quality automation không nằm ở việc phát hiện nhiều vấn đề hơn, mà ở việc biến đúng signal thành đúng hành động với đúng owner.

Nguồn kiểm chứng

Đọc tiếp