Site configuration

SiteConfig provides deployment-wide defaults.

Define a site config

The repository's example site config populates every available field:

quant_ranger_example_plugin/site_config.py

from quant_ranger.site_config import (
    CommitAuthor,
    CopierMigration,
    PullRequestTemplate,
    PullRequestTemplates,
    SiteConfig,
)

site_config = SiteConfig(
    default_owner="octo-org",
    default_github_api_url="https://api.github.com",
    pixi_version_setup_pixi_marker="prefix-dev/setup-pixi",
    pull_request_templates=PullRequestTemplates(
        github_app_token=PullRequestTemplate(
            title="chore: Update GitHub App token inputs",
            body="Use the current inputs for GitHub App authentication.",
            branch_prefix="github-app-token-client-id",
        ),
        node_dependency_cooldown=PullRequestTemplate(
            title="chore: Add Node dependency safeguards",
            body="Configure minimum release ages for Node dependencies.",
            branch_prefix="node-dependency-cooldown-fixes",
        ),
        zizmor=PullRequestTemplate(
            title="chore: Fix GitHub Actions findings",
            body="Apply automated fixes to GitHub Actions workflows.",
            branch_prefix="zizmor-fixes",
        ),
    ),
    copier_migrations={
        "enable-example-feature": CopierMigration(
            answer_key="example_feature",
            templates=frozenset(
                {"github.com/quantco/copier-template-python-open-source"}
            ),
            resolve_desired_value=lambda _current_value: True,
            pull_request_template=PullRequestTemplate(
                title="chore: Enable the example feature",
                body="Enable the example Copier template feature.",
                branch_prefix="copier-migration",
            ),
        )
    },
    fallback_commit_author=CommitAuthor(
        name="example-ranger[bot]",
        email="1+example-ranger[bot]@users.noreply.github.com",
    ),
    copier_trusted_templates=frozenset(
        {"github.com/quantco/copier-template-python-open-source"}
    ),
)

Overall, this configuration class contains:

• Trusted Copier templates (here copier-template-python-open-source)
• PR descriptions and branch prefixes for updaters
• Copier migrations
• Miscellaneous settings such as GitHub API URL, commit author, etc.

The example's full pyproject.toml registers the site config alongside its updater and aggregator:

This allowlists copier-template-python-open-source, Quantco's reviewed open-source Python project template. Add your own templates the same way.

examples/plugin/pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "quant-ranger-example-plugin"
description = "Example plugin package for quant-ranger."
version = "0.1.0"
requires-python = ">=3.14"

[tool.hatch.build.targets.wheel]
packages = ["quant_ranger_example_plugin"]

[project.entry-points."quant_ranger.updaters"]
ensure_config = "quant_ranger_example_plugin.updater:EnsureConfigUpdater"

[project.entry-points."quant_ranger.aggregators"]
status_summary = "quant_ranger_example_plugin.aggregator:StatusSummaryAggregator"

[project.entry-points."quant_ranger.site_config"]
example = "quant_ranger_example_plugin.site_config:site_config"

Install the site config

The example plugin includes the site config shown above. Follow Install and verify to install it into the same environment as quant-ranger.

Verify it is loaded

quant-ranger update --help

The --owner option shows the configured default_owner as its default.

Options

Field	Type	Purpose
default_owner	str | None	Owner for bare names in repository selection. --owner overrides it.
default_github_api_url	str	REST API root for GitHub Enterprise. --github-api-url overrides it.
pixi_version_setup_pixi_marker	str	Default marker used by pixi-version.
pull_request_templates	PullRequestTemplates	Titles, bodies, and branch prefixes used by zizmor, github-app-token, and node-dependency-cooldown.
fallback_commit_author	CommitAuthor	Commit identity used with GitHub App authentication. Personal tokens use the authenticated user.
copier_trusted_templates	frozenset[str]	Complete host/owner/repository allowlist used by Copier template trust.
copier_migrations	Mapping[str, CopierMigration]	Named migrations exposed by copier-migration. Setting this replaces the built-in example entirely.

See the SiteConfig source for the current built-in values.

Customize pull-request templates

PullRequestTemplates contains templates for zizmor, node-dependency-cooldown, and github-app-token. Copier migrations own their pull-request text instead. Each template sets the title, the body, and the branch_prefix of its managed branch. Use dataclasses.replace when only one template differs:

from dataclasses import replace

from quant_ranger.site_config import (
    DEFAULT_PULL_REQUEST_TEMPLATES,
    PullRequestTemplate,
    SiteConfig,
)

site_config = SiteConfig(
    pull_request_templates=replace(
        DEFAULT_PULL_REQUEST_TEMPLATES,
        zizmor=PullRequestTemplate(
            title="chore: apply GitHub Actions fixes",
            body="Automated fixes produced by quant-ranger.",
            branch_prefix="zizmor-updater",
        ),
    ),
)

Define Copier migrations

The copier-migration updater uses each CopierMigration to select the lowercase host/owner/name templates it applies to and an answer key from .copier-answers.yml. Its resolver receives the current boolean, integer, or string value and returns the desired value. Returning the current value skips the repository as up to date. The migration also owns its pull-request template and may provide an optional post-migration hook. A migration's templates control only its eligibility. copier_trusted_templates independently controls whether Copier receives --trust.

from quant_ranger.site_config import (
    CopierMigration,
    PullRequestTemplate,
    SiteConfig,
)

site_config = SiteConfig(
    copier_migrations={
        "enable-feature": CopierMigration(
            answer_key="enable_feature",
            templates=frozenset({"github.com/octo-org/python-template"}),
            resolve_desired_value=lambda _current_value: True,
            pull_request_template=PullRequestTemplate(
                title="chore: Enable the feature",
                body="Enable the Copier template feature.",
                branch_prefix="copier-migration",
            ),
        )
    },
)

Trusted Copier templates execute code

copier_trusted_templates entries are normalized to lowercase and must use host/owner/repository form. Only list repositories whose release tags are protected and reviewed. Copier receives the runner's GitHub token.