Skip to content

API

The top-level package for the project.

rig

CodeQL overrides of pyrig's scaffolding and maintenance layer.

Mirrors pyrig's own rig namespace so its plugin-discovery mechanism automatically picks up this package's overrides and additions.

configs

Declarative definitions of the configuration files managed by this plugin.

This package is this plugin's discovery scope for pyrig's config-file management: every file this plugin manages or overrides is defined here.

version_control

CodeQL customizations for generated version-control configuration.

remote

CodeQL customizations for generated GitHub remote-repository configuration.

code_analyzer

CodeQL-specific configuration for source code analysis.

CodeAnalyzerConfigFile

Bases: YMLDictConfigFile

Configuration consumed by the CodeQL init action's config-file input.

Manages the CodeQL-specific .github/codeql.yml file, including the query suite and ignored paths.

parent_path 
parent_path() -> Path

Return GitHub's special repository configuration directory.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/code_analyzer.py 
22
23
24
25
@override
def parent_path(self) -> Path:
    """Return GitHub's special repository configuration directory."""
    return RemoteVersionController.I.config_dir()
stem 
stem() -> str

Return 'codeql'.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/code_analyzer.py 
27
28
29
30
@override
def stem(self) -> str:
    """Return `'codeql'`."""
    return CodeAnalyzer.I.name()
workflows

CodeQL-specific GitHub Actions workflow configuration.

code_analysis

Reusable code analysis and code-scanning alert gate.

CodeAnalysisWorkflowConfigFile

Bases: WorkflowConfigFile

Analyze Python and GitHub Actions code and fail on open CodeQL alerts.

action_codeql_analyze 
action_codeql_analyze() -> tuple[str, str, str]

Return the pinned CodeQL analyze action metadata.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
112
113
114
def action_codeql_analyze(self) -> tuple[str, str, str]:
    """Return the pinned CodeQL analyze action metadata."""
    return self.action_from_resource(self.action_codeql_analyze, resources)
action_codeql_init 
action_codeql_init() -> tuple[str, str, str]

Return the pinned CodeQL init action metadata.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
116
117
118
def action_codeql_init(self) -> tuple[str, str, str]:
    """Return the pinned CodeQL init action metadata."""
    return self.action_from_resource(self.action_codeql_init, resources)
job_analyze 
job_analyze() -> dict[str, Any]

Build the matrix job that analyzes Python and workflow code.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
43
44
45
46
47
48
49
50
51
52
53
def job_analyze(self) -> dict[str, Any]:
    """Build the matrix job that analyzes Python and workflow code."""
    return self.job(
        self.job_analyze,
        strategy=self.strategy_matrix(
            matrix=self.matrix({"language": ["python", "actions"]}),
        ),
        permissions=self.job_analyze_permissions(),
        steps=self.steps_analyze(),
        timeout_minutes=90,
    )
job_analyze_permissions 
job_analyze_permissions() -> dict[str, str]

Grant the permissions required to analyze and upload CodeQL results.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
63
64
65
66
67
68
69
def job_analyze_permissions(self) -> dict[str, str]:
    """Grant the permissions required to analyze and upload CodeQL results."""
    return {
        **self.permission_contents(),
        **self.permission("actions"),
        **self.permission("security-events", write=True),
    }
job_check_alerts 
job_check_alerts() -> dict[str, Any]

Check CodeQL alerts after all language analyses have completed.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
33
34
35
36
37
38
39
40
41
def job_check_alerts(self) -> dict[str, Any]:
    """Check CodeQL alerts after all language analyses have completed."""
    return self.job(
        self.job_check_alerts,
        needs=(self.job_analyze,),
        permissions=self.job_check_alerts_permissions(),
        steps=self.steps_check_alerts(),
        timeout_minutes=5,
    )
job_check_alerts_permissions 
job_check_alerts_permissions() -> dict[str, str]

Grant read access to code-scanning alerts.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
55
56
57
def job_check_alerts_permissions(self) -> dict[str, str]:
    """Grant read access to code-scanning alerts."""
    return self.permission("security-events")
jobs 
jobs() -> tuple[Callable[[], dict[str, Any]], ...]

Return the analysis and alert-gate jobs.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
18
19
20
21
@override
def jobs(self) -> tuple[Callable[[], dict[str, Any]], ...]:
    """Return the analysis and alert-gate jobs."""
    return (self.job_analyze, self.job_check_alerts)
stem 
stem() -> str

Return the workflow filename stem.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
23
24
25
26
@override
def stem(self) -> str:
    """Return the workflow filename stem."""
    return "code-analysis"
step_analyze_code 
step_analyze_code() -> dict[str, Any]

Run the CodeQL analysis and upload its results.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
94
95
96
97
98
99
def step_analyze_code(self) -> dict[str, Any]:
    """Run the CodeQL analysis and upload its results."""
    return self.step(
        self.step_analyze_code,
        uses=self.action_codeql_analyze(),
    )
step_check_alerts 
step_check_alerts() -> dict[str, Any]

Fail if the analyzed ref has any open CodeQL alerts.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def step_check_alerts(self) -> dict[str, Any]:
    """Fail if the analyzed ref has any open CodeQL alerts."""
    return self.step(
        self.step_check_alerts,
        run=RemoteVersionController.I.api_method_args(
            '--raw-field="ref=${GITHUB_REF}"',
            "--raw-field=state=open",
            "--raw-field=tool_name=CodeQL",
            """--jq='if . != [] then error("Alerts found") end'""",
            endpoint='"repos/${GITHUB_REPOSITORY}/code-scanning/alerts"',
            method="GET",
        ).multiline(),
        env={"GH_TOKEN": self.insert_github_token()},
    )
step_initialize_codeql 
step_initialize_codeql() -> dict[str, Any]

Initialize CodeQL for the current matrix language.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
101
102
103
104
105
106
107
108
109
110
def step_initialize_codeql(self) -> dict[str, Any]:
    """Initialize CodeQL for the current matrix language."""
    return self.step(
        self.step_initialize_codeql,
        uses=self.action_codeql_init(),
        with_={
            "languages": self.insert_expression("matrix.language"),
            "config-file": CodeAnalyzerConfigFile.I.path().as_posix(),
        },
    )
steps_analyze 
steps_analyze() -> list[dict[str, Any]]

Return checkout, initialization, and analysis steps.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
86
87
88
89
90
91
92
def steps_analyze(self) -> list[dict[str, Any]]:
    """Return checkout, initialization, and analysis steps."""
    return [
        self.step_checkout_repository(),
        self.step_initialize_codeql(),
        self.step_analyze_code(),
    ]
steps_check_alerts 
steps_check_alerts() -> list[dict[str, Any]]

Return the CodeQL alert-check step.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
59
60
61
def steps_check_alerts(self) -> list[dict[str, Any]]:
    """Return the CodeQL alert-check step."""
    return [self.step_check_alerts()]
workflow_triggers 
workflow_triggers() -> dict[str, Any]

Allow invocation only through a reusable-workflow call.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/code_analysis.py 
28
29
30
31
@override
def workflow_triggers(self) -> dict[str, Any]:
    """Allow invocation only through a reusable-workflow call."""
    return self.on_workflow_call()
health_check

Health check workflow extended with code analysis and an open-alert gate.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Include the reusable code-analysis workflow in the health check.

job_code_analysis 
job_code_analysis() -> dict[str, Any]

Call the reusable code-analysis workflow.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
26
27
28
29
30
31
def job_code_analysis(self) -> dict[str, Any]:
    """Call the reusable code-analysis workflow."""
    return self.job_workflow_call(
        self.job_code_analysis,
        workflow=CodeAnalysisWorkflowConfigFile,
    )
jobs_health_check 
jobs_health_check() -> (
    tuple[Callable[[], dict[str, Any]], ...]
)

Return the base health-check jobs followed by the code-analysis call.

Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
18
19
20
21
22
23
24
@override
def jobs_health_check(self) -> tuple[Callable[[], dict[str, Any]], ...]:
    """Return the base health-check jobs followed by the code-analysis call."""
    return (
        *super().jobs_health_check(),
        self.job_code_analysis,
    )

resources

Static resource files bundled with the project.

tools

CodeQL tool integrations.

security

Tool wrappers for code-security analysis.

code

CodeQL tool identity and code-analysis badge metadata.

CodeAnalyzer

Bases: Tool

Represent CodeQL, which runs through GitHub Actions.

dev_dependencies 
dev_dependencies() -> tuple[str, ...]

Return no dev dependencies because CodeQL runs in GitHub Actions.

Source code in src/pyrig_codeql/rig/tools/security/code.py 
11
12
13
14
@override
def dev_dependencies(self) -> tuple[str, ...]:
    """Return no dev dependencies because CodeQL runs in GitHub Actions."""
    return ()
group 
group() -> str

Return Group.CODE_QUALITY.

Source code in src/pyrig_codeql/rig/tools/security/code.py 
16
17
18
19
@override
def group(self) -> str:
    """Return `Group.CODE_QUALITY`."""
    return Group.CODE_QUALITY
image_url 
image_url() -> str

Return a badge identifying CodeQL as the project's code analyzer.

Source code in src/pyrig_codeql/rig/tools/security/code.py 
21
22
23
24
@override
def image_url(self) -> str:
    """Return a badge identifying CodeQL as the project's code analyzer."""
    return "https://img.shields.io/badge/code--analysis-CodeQL-181717?logo=github"
link_url 
link_url() -> str

Return the CodeQL documentation URL.

Source code in src/pyrig_codeql/rig/tools/security/code.py 
26
27
28
29
@override
def link_url(self) -> str:
    """Return the CodeQL documentation URL."""
    return "https://codeql.github.com/docs/"
name 
name() -> str

Return the CodeQL tool identity.

Source code in src/pyrig_codeql/rig/tools/security/code.py 
31
32
33
34
@override
def name(self) -> str:
    """Return the CodeQL tool identity."""
    return "codeql"