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 configuration that restricts analysis to shipped source code.

CodeAnalyzerConfigFile

Bases: YMLDictConfigFile

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

Manages .github/codeql.yml, 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 
19
20
21
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 
23
24
25
def stem(self) -> str:
    """Return `'codeql'`."""
    return "codeql"
workflows

CodeQL-specific GitHub Actions workflow configuration.

health_check

Health check workflow extended with a CodeQL analysis job.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Health check workflow extended with a CodeQL analysis job.

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

Return action metadata for github/codeql-action/analyze.

Returns:

Type Description
tuple[str, str, str]

Tuple of action name, pinned commit SHA, and release tag.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
115
116
117
118
119
120
121
def codeql_analyze_action(self) -> tuple[str, str, str]:
    """Return action metadata for `github/codeql-action/analyze`.

    Returns:
        Tuple of action name, pinned commit SHA, and release tag.
    """
    return self.action_from_resource(self.codeql_analyze_action, resources)
codeql_init_action 
codeql_init_action() -> tuple[str, str, str]

Return action metadata for github/codeql-action/init.

Returns:

Type Description
tuple[str, str, str]

Tuple of action name, pinned commit SHA, and release tag.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
107
108
109
110
111
112
113
def codeql_init_action(self) -> tuple[str, str, str]:
    """Return action metadata for `github/codeql-action/init`.

    Returns:
        Tuple of action name, pinned commit SHA, and release tag.
    """
    return self.action_from_resource(self.codeql_init_action, resources)
job_analyze 
job_analyze() -> dict[str, Any]

Return the CodeQL analysis job.

Returns:

Type Description
dict[str, Any]

Job configuration with a matrix over ("python", "actions"),
dict[str, Any]

the permissions CodeQL needs to build a database and upload its
dict[str, Any]

results, and the analysis steps.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def job_analyze(self) -> dict[str, Any]:
    """Return the CodeQL analysis job.

    Returns:
        Job configuration with a matrix over `("python", "actions")`,
        the permissions CodeQL needs to build a database and upload its
        results, and the analysis steps.
    """
    return self.job(
        self.job_analyze,
        strategy=self.strategy_matrix(
            matrix=self.matrix({"language": ["python", "actions"]}),
        ),
        permissions={
            **self.permission_contents(),
            **self.permission("actions"),
            **self.permission("security-events", write=True),
        },
        steps=self.steps_analyze(),
    )
job_health_check_needs 
job_health_check_needs() -> tuple[MethodType, ...]

Return the upstream jobs required before the aggregate job runs.

Prepends the CodeQL analysis job to the two base health-check jobs so the aggregate status remains a release gate for every analysis.

Returns:

Type Description
tuple[MethodType, ...]

The base class's dependencies plus the CodeQL analysis job.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
30
31
32
33
34
35
36
37
38
39
def job_health_check_needs(self) -> tuple[MethodType, ...]:
    """Return the upstream jobs required before the aggregate job runs.

    Prepends the CodeQL analysis job to the two base health-check jobs so
    the aggregate status remains a release gate for every analysis.

    Returns:
        The base class's dependencies plus the CodeQL analysis job.
    """
    return (self.job_analyze, *super().job_health_check_needs())
jobs 
jobs() -> dict[str, Any]

Return the base class's jobs, extended with the CodeQL analysis job.

Returns:

Type Description
dict[str, Any]

The base class jobs plus the CodeQL analysis job.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
19
20
21
22
23
24
25
26
27
28
def jobs(self) -> dict[str, Any]:
    """Return the base class's jobs, extended with the CodeQL analysis job.

    Returns:
        The base class jobs plus the CodeQL analysis job.
    """
    return {
        **self.job_analyze(),
        **super().jobs(),
    }
step_analyze_code 
step_analyze_code() -> dict[str, Any]

Build a step that runs the CodeQL analysis and uploads results.

Fails the job if the analysis itself fails to run; code scanning alerts found by the analysis do not fail the step.

Returns:

Type Description
dict[str, Any]

Step using github/codeql-action/analyze@<ref>.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def step_analyze_code(self) -> dict[str, Any]:
    """Build a step that runs the CodeQL analysis and uploads results.

    Fails the job if the analysis itself fails to run; code scanning
    alerts found by the analysis do not fail the step.

    Returns:
        Step using `github/codeql-action/analyze@<ref>`.
    """
    return self.step(
        self.step_analyze_code,
        uses=self.codeql_analyze_action(),
    )
step_initialize_codeql 
step_initialize_codeql() -> dict[str, Any]

Build a step that initializes the CodeQL database.

Neither analyzed language is compiled, so no build step is required between initialization and analysis.

Returns:

Type Description
dict[str, Any]

Step using github/codeql-action/init@<ref>.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def step_initialize_codeql(self) -> dict[str, Any]:
    """Build a step that initializes the CodeQL database.

    Neither analyzed language is compiled, so no build step is
    required between initialization and analysis.

    Returns:
        Step using `github/codeql-action/init@<ref>`.
    """
    return self.step(
        self.step_initialize_codeql,
        uses=self.codeql_init_action(),
        with_={
            "languages": self.insert_expression("matrix.language"),
            "config-file": CodeAnalyzerConfigFile.I.path().as_posix(),
        },
    )
steps_analyze 
steps_analyze() -> list[dict[str, Any]]

Return the steps for the CodeQL analysis job.

Returns:

Type Description
list[dict[str, Any]]

Steps that check out the repository, initialize CodeQL for the
list[dict[str, Any]]

current matrix language, and run the analysis.
Source code in src/pyrig_codeql/rig/configs/version_control/remote/workflows/health_check.py 
62
63
64
65
66
67
68
69
70
71
72
73
def steps_analyze(self) -> list[dict[str, Any]]:
    """Return the steps for the CodeQL analysis job.

    Returns:
        Steps that check out the repository, initialize CodeQL for the
        current matrix language, and run the analysis.
    """
    return [
        self.step_checkout_repository(),
        self.step_initialize_codeql(),
        self.step_analyze_code(),
    ]

resources

Static resource files bundled with the project.