Skip to content

docs(ops): document CodeQL dual-source conflict and Zizmor every-PR enforce #1764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FabioLeitao merged 1 commit into from
Aug 27, 2026
Merged

docs(ops): document CodeQL dual-source conflict and Zizmor every-PR enforce #1764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .github/workflows/codeql.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
# CodeQL: security and quality analysis for Python (OWASP, injection, etc.).
# Results appear under Security > Code scanning; configure rulesets for merge protection.
# https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning
# (verify: default-setup disabled 2026-08-25, this custom workflow is the sole CodeQL source of truth now, badge restored -- issue #1757)
#
# Conflict: GitHub default setup (path dynamic/github-code-scanning/codeql) and this
# advanced workflow cannot both upload SARIF. When default setup is enabled, Analyze
# fails with: "CodeQL analyses from advanced configurations cannot be processed when
# the default setup is enabled." Check live state with `gh workflow list --all`
# (two rows named CodeQL). Keep init/analyze action SHAs in lockstep. Issue #1757.
#
# Actions pinned to full commit SHAs (tag in comment); bump via Dependabot or after upstream review.
#
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ GitHub **rulesets** plus classic branch protection apply to **`main`**. This sec
- **Required status checks** (merge-blocking, ruleset `main-gate-pii`): **Test (Python 3.12)**, **Test (Python 3.13)**, **Test (Python 3.14)**.
- **Signed commits** are required (classic protection and ruleset `restriction baseline`). Dependabot cannot receive unsigned pushes from Actions — use the sync workflow handoff or a signed supersede PR ([#1419](https://github.com/DataBoar/data-boar/issues/1419); [docs/ops/DEPENDABOT_REQUIREMENTS_SYNC.md](docs/ops/DEPENDABOT_REQUIREMENTS_SYNC.md)).
- **Approving reviews** are **not** required (`required_approving_review_count: 0`). [`.github/CODEOWNERS`](.github/CODEOWNERS) exists for PII/security gate paths; the ruleset does **not** currently require code-owner review.
- **Lint, Bandit, Windows pytest, Semgrep, CodeQL, Sonar, Zizmor** usually run on the PR. Treat a red job as a stop even when GitHub would still allow merge. **`ZIZMOR_ENFORCE=true`** fails the Zizmor job on workflow-path changes; that job is **not** a required check.
- **Lint, Bandit, Windows pytest, Semgrep, CodeQL, Sonar, Zizmor** usually run on the PR. Treat a red job as a stop even when GitHub would still allow merge. **Zizmor** runs on **every** push/PR (**no** path filter) and **fails** unless **`ZIZMOR_ENFORCE=false`**; that job is **not** a required check. **CodeQL** uses `.github/workflows/codeql.yml`; do not leave GitHub **default setup** enabled at the same time ([docs/TESTING.md](docs/TESTING.md) *CodeQL*).
- **Before you push:** run **`./scripts/check-all.sh`** or **`.\scripts\check-all.ps1`**. Merge helpers: [docs/ops/COMMIT_AND_PR.md](docs/ops/COMMIT_AND_PR.md), `scripts/pr-merge-when-green.ps1`.

Do **not** change GitHub protection settings from a docs PR. If the live UI disagrees with the runbook, re-query `gh api` and update the runbook.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.pt_BR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ O Cursor registra isso em **`.cursor/rules/git-pr-sync-before-advice.mdc`**. Vej
- **Status checks obrigatórios** (bloqueiam merge, ruleset `main-gate-pii`): **Test (Python 3.12)**, **Test (Python 3.13)**, **Test (Python 3.14)**.
- **Commits assinados** são obrigatórios (proteção clássica e ruleset `restriction baseline`). O Dependabot não recebe push unsigned do Actions — use o handoff do workflow de sync ou um PR substituto assinado ([#1419](https://github.com/DataBoar/data-boar/issues/1419); [docs/ops/DEPENDABOT_REQUIREMENTS_SYNC.pt_BR.md](docs/ops/DEPENDABOT_REQUIREMENTS_SYNC.pt_BR.md)).
- **Revisões aprovadoras** **não** são obrigatórias (`required_approving_review_count: 0`). [`.github/CODEOWNERS`](.github/CODEOWNERS) cobre os caminhos do gate de PII/segurança; o ruleset **ainda não** exige revisão de code owner.
- **Lint, Bandit, pytest Windows, Semgrep, CodeQL, Sonar, Zizmor** costumam rodar no PR. Trate um job vermelho como pare mesmo quando o GitHub ainda permitiria merge. **`ZIZMOR_ENFORCE=true`** falha o job Zizmor em mudanças de workflow; esse job **não** é check obrigatório.
- **Lint, Bandit, pytest Windows, Semgrep, CodeQL, Sonar, Zizmor** costumam rodar no PR. Trate um job vermelho como pare mesmo quando o GitHub ainda permitiria merge. O **Zizmor** roda em **todo** push/PR (**sem** filtro de path) e **falha** salvo **`ZIZMOR_ENFORCE=false`**; esse job **não** é check obrigatório. O **CodeQL** usa `.github/workflows/codeql.yml`; **não** deixe o **default setup** do GitHub ligado ao mesmo tempo ([docs/TESTING.pt_BR.md](docs/TESTING.pt_BR.md) *CodeQL*).
- **Antes do push:** rode **`./scripts/check-all.sh`** ou **`.\scripts\check-all.ps1`**. Ajudas de merge: [docs/ops/COMMIT_AND_PR.pt_BR.md](docs/ops/COMMIT_AND_PR.pt_BR.md), `scripts/pr-merge-when-green.ps1`.

**Não** altere as configurações de proteção do GitHub num PR só de docs. Se a UI ao vivo divergir do runbook, consulte o `gh api` de novo e atualize o runbook.
Expand Down
4 changes: 2 additions & 2 deletions docs/GLOSSARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,9 +139,9 @@ Terms are grouped by **theme** (product, scanning workflow, compliance, APIs, et
| **Sigstore** | Keyless artifact / attestation signing with a public transparency log (cosign, Fulcio, Rekor); pairs with **provenance** and **SBOM** for verifiable supply chains. **See also:** **attestation**, **SBOM**. |
| **SAST** | **Static Application Security Testing**: analysis of **source code** (and sometimes bytecode) without running the full app—e.g. **CodeQL**, **Semgrep**, **Bandit** in **CI**. Complements manual review and runtime tests; not a guarantee of absence of bugs. This repo runs selected tools in pipelines; see **SECURITY.md** and `.github/workflows/`. **See also:** **CVE**, **shift-left security**. |
| **Bandit** | Python **SAST** linter for common security issues (subprocess, eval, weak crypto). Data Boar's strict CI gate runs `bandit -r . -c pyproject.toml -ll -ii` (MEDIUM+ severity **and** confidence). **See also:** **SAST**, **CI/CD**. |
| **CodeQL** | GitHub's semantic code-analysis engine: queries code **as a database** to find security patterns. Runs on push / PR and on a weekly schedule. **See also:** **SAST**, **Semgrep**. |
| **CodeQL** | GitHub's semantic code-analysis engine: queries code **as a database** to find security patterns. This repo's advanced workflow is `.github/workflows/codeql.yml` (push / PR / weekly). GitHub **default setup** (`dynamic/github-code-scanning/codeql`) **cannot** run at the same time — GitHub rejects advanced SARIF while default setup is enabled. **See also:** **SAST**, **Semgrep**; [TESTING.md](TESTING.md). |
| **Semgrep** | Fast, pattern-based **SAST** across many languages. Data Boar runs the OSS `p/python` ruleset in CI. **See also:** **SAST**, **CodeQL**. |
| **zizmor** | Security linter for **GitHub Actions** workflows (token scope, script injection, unpinned actions). An **enforced** CI gate (issue #732), with an optional local pre-commit stage via `scripts/workflow-security-lint`. **See also:** **SAST**, **CI/CD**, **least privilege**. |
| **zizmor** | Security linter for **GitHub Actions** workflows (token scope, script injection, unpinned actions). The CI **job fails by default** (issue #732; opt out: repo variable **`ZIZMOR_ENFORCE=false`**). It is **not** a required merge check. Runs on every push/PR (**no** path filter). Optional local pre-commit stage via `scripts/workflow-security-lint`. **See also:** **SAST**, **CI/CD**, **least privilege**. |
| **Gitleaks** | Secret-scanning tool that flags committed credentials and keys across the working tree and Git history. Runs as a dedicated CI gate. **See also:** **SAST**, **CI/CD**. |
| **SonarQube / SonarCloud** | Continuous code-quality and security-hotspot platform; a token-gated CI gate tracking maintainability, reliability, and security findings. **See also:** **SAST**, **CI/CD**. |
| **pip-audit** | Audits installed Python dependencies against known vulnerability advisories (**CVE** / PyPI); the CI dependency-audit gate. **See also:** **CVE**, **SBOM**. |
Expand Down
Loading