Compliance Scanning via GitHub Actions — Broad Policy as Code Across a…

Research Question

How can GitHub Actions (with GitHub Advanced Security (GHAS) and CodeQL already enabled) be extended to enforce a broad, organisation-wide compliance policy — covering naming conventions, architectural patterns, directory layout, Application Programming Interface (API) specifications, event schemas, and technology-stack-specific usage rules — across a heterogeneous estate of .NET, Kubernetes (k8s), Python, React, Go, Airflow, DBT (Data Build Tool), Snowflake, Relational Database Service (RDS), Terraform, Ansible, Representational State Transfer (REST) APIs, Graph APIs (GraphQL), and event-driven systems, where policies are defined once and shared across multiple enforcement points?

Findings

Executive Summary

• [inference] The most defensible way to extend GHAS and CodeQL into broad compliance scanning is to treat them as the supported-language security layer inside a larger GitHub Actions architecture that also governs manifests, schemas, SQL, and project structure. Basis: GitHub Docs — About code scanning with CodeQL ; GitHub Docs — Reusable workflows ; GitHub Docs — Available rules for rulesets / require workflows to pass before merging
• [fact] GitHub already provides the cross-repository control-plane primitives needed for that design: reusable workflows centralise execution logic, while organisation rulesets and required status checks make shared checks mandatory. Sources: GitHub Docs — Reusable workflows ; GitHub Docs — Creating organisation rulesets
• [inference] The correct operating model is a multi-tool policy portfolio organised by artefact type, not an attempt to stretch CodeQL into every compliance domain named in the question. Basis: CodeQL docs — Supported languages and frameworks ; Checkov repository ; Spectral repository and documentation entry point ; GraphQL Inspector docs ; SQLFluff documentation ; dbt-project-evaluator repository
• [inference] The safest adoption path is to centralise policy artefacts, run them first in Evaluate or soft-fail mode, and only then promote them into merge-blocking rulesets after outputs, ownership, and exceptions are stable. Basis: GitHub Well-Architected — Rulesets best practices ; AWS Prescriptive Guidance — centralised custom Checkov scanning

Key Findings

1. [inference][high] Because the CodeQL support matrix is language-centric, any estate that also needs Terraform, Kubernetes, OpenAPI, AsyncAPI, SQL, or dbt governance must add dedicated artefact scanners instead of expecting GHAS alone to enforce those surfaces. Basis: GitHub Docs — About code scanning with CodeQL ; CodeQL docs — Supported languages and frameworks
2. [fact][high] GitHub separates shared execution from shared enforcement: reusable workflows encapsulate the shared scanning logic, while organisation rulesets and required checks apply merge-blocking governance across targeted repositories. Sources: GitHub Docs — Reusable workflows ; GitHub Docs — Creating organisation rulesets ; GitHub Docs — Available rules for rulesets / require workflows to pass before merging
3. [fact][high] CodeQL packs are an important extension point for supported languages, but the official pack model still assumes CodeQL-compatible artefacts and therefore cannot replace specialised validation tools for schemas, manifests, and SQL-focused repositories. Sources: GitHub Docs — CodeQL custom queries and packs ; CodeQL docs — Supported languages and frameworks
4. [fact][high] The open-source toolchain retrieved in this item is already broad enough to cover most of the named estate when organised by artefact type, combining Semgrep and Conftest for generic policy, Checkov and kube-score for IaC and Kubernetes, Spectral and AsyncAPI CLI for API and event contracts, GraphQL Inspector for GraphQL, and SQLFluff plus dbt-project-evaluator for data-platform governance. Sources: Semgrep rule-writing overview ; Open Policy Agent (OPA) / Conftest ; Checkov repository ; kube-score repository ; Spectral repository and documentation entry point ; AsyncAPI Command Line Interface (CLI) ; GraphQL Inspector docs ; SQLFluff documentation ; dbt-project-evaluator repository
5. [inference][medium] A central policy-repository model is more maintainable than embedding scanner logic in every application repository, because central rule bundles and reusable workflows reduce drift, simplify ownership, and let policy teams update standards without mass copy-editing downstream repositories. Basis: GitHub Docs — Reusable workflows ; AWS Prescriptive Guidance — centralised custom Checkov scanning ; GitHub Well-Architected — Rulesets best practices
6. [inference][high] A staged rollout with Evaluate mode, soft-fail where appropriate, rule insights, and explicit bypass governance is not just a convenience feature but the operational control that prevents multi-scanner compliance programmes from collapsing under false positives and unstable checks. Basis: GitHub Well-Architected — Rulesets best practices ; AWS Prescriptive Guidance — centralised custom Checkov scanning
7. [inference][medium] The minimum viable architecture for this problem is a portfolio of four reusable workflow domains — code, infrastructure, APIs/events, and data — each backed by centrally versioned policies and attached to repository tiers through organisation rulesets. Basis: GitHub Docs — Reusable workflows ; GitHub Docs — Available rules for rulesets / require workflows to pass before merging ; GitHub Well-Architected — Rulesets best practices
8. [inference][medium] GraphQL and event-driven contract governance deserve first-class treatment in the compliance model, because the retrieved evidence shows dedicated schema-aware tools for those artefacts and does not support treating them as a by-product of generic source-code scanning. Basis: GraphQL Inspector docs ; AsyncAPI Command Line Interface (CLI) ; Spectral repository and documentation entry point

Assumptions

• [assumption] Assumption: The organisation can maintain central policy repositories and a small reusable-workflow portfolio. Justification: Without central ownership, the proposed architecture degenerates into per-repository duplication and loses its main scale advantage.
• [assumption] Assumption: Teams can tolerate an Evaluate or soft-fail adoption period before strict merge blocking. Justification: GitHub and AWS guidance both point to staged rollout as the practical way to reduce developer friction and tune rules.

Analysis

• [inference] The evidence supports a compositional architecture rather than a monolithic scanner strategy. GitHub supplies the orchestration and enforcement layer, while specialised tools supply the domain semantics. Basis: GitHub Docs — Reusable workflows ; GitHub Docs — Available rules for rulesets / require workflows to pass before merging ; Checkov repository ; Spectral repository and documentation entry point ; SQLFluff documentation
• [inference] That compositional design also fits realistic ownership boundaries, because platform or security teams can own shared rules and workflows while application teams remain responsible only for repository-local adoption and exception handling. Basis: AWS Prescriptive Guidance — centralised custom Checkov scanning ; GitHub Well-Architected — Rulesets best practices
• [inference] The main remaining architecture gap is not scanner availability but result normalisation: a serious enterprise rollout will eventually need a common severity, waiver, and reporting model across these otherwise independent tools. Basis: Checkov repository ; Spectral repository and documentation entry point ; GraphQL Inspector docs ; SQLFluff documentation ; dbt-project-evaluator repository

Risks, Gaps, and Uncertainties

• [fact] The original Spectral documentation page supplied in the item was inaccessible during retrieval, so Spectral capability claims rely on the project readme rather than the exact seed page. Sources: Original Stoplight Spectral documentation page in the seed item returned 404 at retrieval time ; Spectral repository and documentation entry point
• [inference] GitHub's required-workflows feature history is partially split between older launch posts and newer rulesets documentation, so any implementation should validate plan support against current product docs for the target organisation. Basis: GitHub Blog — Required workflows and configuration variables ; GitHub Docs — Available rules for rulesets / require workflows to pass before merging
• [inference] GraphQL governance beyond schema diffing and document validation remains underexplored in this item and would benefit from a dedicated follow-up on style, naming, and resolver policy tooling. Basis: GraphQL Inspector docs
• [inference] A common evidence and waiver layer for multi-scanner GitHub Actions compliance remains an open design problem not resolved by the retrieved sources. Basis: gap across the retrieved tool documentation.

Open Questions

• [inference] How should heterogeneous scanner outputs be normalised into one durable evidence model for audit, waiver management, and developer triage inside GitHub?
• [inference] What is the best open-source governance toolchain for GraphQL style and schema policy beyond change detection and operation validation?
• [inference] When central workflows become merge-blocking, which checks should emit GitHub code-scanning alerts versus regular check-run summaries so that developers see one coherent signal instead of many parallel failure surfaces?

sources

• [x] GitHub Docs — Available rules for rulesets / require workflows to pass before merging
• [x] GitHub Docs — Reusable workflows
• [x] GitHub Docs — Creating organisation rulesets
• [x] GitHub Docs — About code scanning with CodeQL
• [x] CodeQL docs — Supported languages and frameworks
• [x] GitHub Docs — CodeQL custom queries and packs
• [x] GitHub Blog — Required workflows and configuration variables
• [x] GitHub Well-Architected — Rulesets best practices
• [x] Open Policy Agent (OPA) / Conftest
• [x] Semgrep rule-writing overview
• [x] Spectral repository and documentation entry point
• [ ] Original Stoplight Spectral documentation page in the seed item returned 404 at retrieval time
• [x] Checkov documentation
• [x] Checkov repository
• [x] AWS Prescriptive Guidance — centralised custom Checkov scanning
• [x] dbt-project-evaluator repository
• [x] SQLFluff documentation
• [x] golangci-lint documentation
• [x] golangci-lint repository
• [x] kube-score repository
• [x] AsyncAPI Command Line Interface (CLI)
• [x] GraphQL Inspector docs
• [x] Ruff docs
• [x] Prior related item — adaptive policy authorisation compliance: Research/completed/2026-03-16-adaptive-policy-authorization-compliance.md
• [x] Prior related item — agent Language Server Protocol (LSP) policy enforcement: Research/completed/2026-03-01-agent-lsp-policy-enforcement.md