Skip to content

livery.workshop._ci_generate

livery.workshop._ci_generate

The CI workflow renderers: the declared points, in each forge's words.

Workflow files are mechanical forge knowledge, emitted here from the workspace contract (workshop.toml) and the derived Python matrix, written as managed generated artifacts, and the drift check compares the committed files against these same pure functions, offline. Change an emitter, run fm sync, and every kind's files move together.

Every job enters through the emitted setup.sh (the entry contract: uv at the lock's pin, the venv synced against the lock, the emission persisted) and then calls the runner bare: no uv run anywhere in a rendered workflow.

The release workflows are the merge-triggered train: publishing runs where the release PR's squash lands, and the receipt tags are cut by fm workflow.release.publish after the index confirms each member, so a tag is a receipt, never a trigger.

Functions:

Name Description
checkout_inputs

Every input the answers add to the checkout step, each name to its value.

generate

Every generated CI file for root's forge kind, by path.

generated_files

The generated artifacts as absolute paths under root.

retired_files

The generated workflow files under root this emission does not own, to delete.

Attributes:

Name Type Description
ACTIONS dict[str, dict[str, str]]
STORE_HOME
CONAN_HOME
DRIVER_DIST

The distribution a re-dispatched wave may pin as its driver.

CHECKOUT_OWN
GENERATED_MARK

ACTIONS module-attribute

ACTIONS: dict[str, dict[str, str]] = {'github': {'checkout': _pinned('actions/checkout', '3d3c42e5aac5ba805825da76410c181273ba90b1', 'v7.0.1'), 'upload': _pinned('actions/upload-artifact', '043fb46d1a93c77aae656e7c1c64a875d1fc6a0a', 'v7.0.1'), 'download': _pinned('actions/download-artifact', '3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c', 'v8.0.1'), 'setup-uv': _pinned('astral-sh/setup-uv', '20cfd1bf945f4377ade1205e4dbc17946fc9a30d', 'v10.0.1'), 'cache': _pinned('actions/cache', '0057852bfaa89a56745cba8c7296529d2fc39830', 'v4.3.0'), 'upload-pages': _pinned('actions/upload-pages-artifact', '7b1f4a764d45c48632c6b24a0339c27f5614fb0b', 'v4.0.0'), 'deploy-pages': _pinned('actions/deploy-pages', 'd6db90164ac5ed86f2b6aed7e0febac5b3c0c03e', 'v4.0.5')}, 'gitea': {'checkout': _pinned('actions/checkout', '11d5960a326750d5838078e36cf38b85af677262', 'v4.4.0'), 'upload': _pinned('actions/upload-artifact', 'ea165f8d65b6e75b540449e92b4886f43607fa02', 'v4.6.2'), 'download': _pinned('actions/download-artifact', 'd3f86a106a0bac45b974a628896c90dbdf5c8093', 'v4.3.0')}}

STORE_HOME module-attribute

STORE_HOME = '${{ runner.temp }}/footman/toolroom'

CONAN_HOME module-attribute

CONAN_HOME = '${{ runner.temp }}/conan'

DRIVER_DIST module-attribute

DRIVER_DIST = 'livery-workshop'

The distribution a re-dispatched wave may pin as its driver.

CHECKOUT_OWN module-attribute

CHECKOUT_OWN = ('ref', 'fetch-depth', 'fetch-tags', 'token')

GENERATED_MARK module-attribute

GENERATED_MARK = '# Generated by the workshop from workshop.toml'

checkout_inputs

checkout_inputs(answers: Mapping[str, Any], lookup: Lookup) -> dict[str, str]

Every input the answers add to the checkout step, each name to its value.

The rule of the checkout-inputs query, which the base's contract file names. Each answer maps an input of the checkout action to its value, written into the workflow as it stands.

Raises:

Type Description
QueryError

when an answer names an input the step sets from the job's declaration (CHECKOUT_OWN) or gives a value that is not a string, naming the extension, or when two answers give one input different values, naming both.

Source code in packages/workshop/src/livery/workshop/_ci_generate.py
def checkout_inputs(answers: Mapping[str, Any], lookup: Lookup) -> dict[str, str]:
    """Every input the answers add to the checkout step, each name to its value.

    The rule of the ``checkout-inputs`` query, which the base's
    contract file names. Each answer maps an input of the checkout
    action to its value, written into the workflow as it stands.

    Raises:
        QueryError: when an answer names an input the step sets from the
            job's declaration (``CHECKOUT_OWN``) or gives a value that is
            not a string, naming the extension, or when two answers give
            one input different values, naming both.
    """
    from livery.workshop._queries import QueryError, merged

    for name, value in answers.items():
        for key, held in cast("Mapping[str, object]", value).items():
            if key in CHECKOUT_OWN:
                raise QueryError(
                    f"{name} answers {key}, which the checkout step sets from"
                    " the job's declaration; answer another input"
                )
            if not isinstance(held, str):
                raise QueryError(
                    f"{name} answers {key} with {held!r}, and an input's value"
                    " is a string, as the workflow writes it; quote it"
                )
    return dict(merged(answers, lookup))

generate

generate(root: Path) -> dict[str, str]

Every generated CI file for root's forge kind, by path.

The workflows call the CLI by the name this process runs under, so a branded runner emits workflows that call itself and needs no configuration. The emitted setup.sh at the root is the entry every workflow's jobs share. The template-artifact job is emitted only for a home: the contract declares where to publish and a member extension ships the tree; an ordinary instance's release has no templates to publish.

Source code in packages/workshop/src/livery/workshop/_ci_generate.py
def generate(root: Path) -> dict[str, str]:
    """Every generated CI file for *root*'s forge kind, by path.

    The workflows call the CLI by the name this process runs under,
    so a branded runner emits workflows that call itself and needs
    no configuration. The emitted ``setup.sh`` at the root is the
    entry every workflow's jobs share. The template-artifact job is
    emitted only for a home: the contract declares where to publish
    and a member extension ships the tree; an ordinary instance's
    release has no templates to publish.
    """
    from livery.workshop._entry import entry_script
    from livery.workshop._provenance import generated_header

    prog = footman.prog()
    everything = emitted_points(root)
    facts = _facts(root, everything)
    kind = str(facts["forge_kind"])
    header = generated_header("#")
    if kind in ("github", "gitea"):
        # One file per workflow: the gate and the merge point share
        # ci.yml, the nightly, the release and every contributed point
        # have their own.
        workflows = sorted({point.workflow for point in everything})
        files = {
            f".{kind}/workflows/{workflow}": _actions_workflow(
                facts, prog, workflow, forge=kind, everything=everything
            )
            for workflow in workflows
        }
    else:
        files = {".gitlab-ci.yml": _gitlab_document(facts, prog, everything=everything)}
    files["setup.sh"] = entry_script(root)
    return {path: header + content for path, content in files.items()}

generated_files

generated_files(root: Path) -> dict[Path, str]

The generated artifacts as absolute paths under root.

Source code in packages/workshop/src/livery/workshop/_ci_generate.py
def generated_files(root: Path) -> dict[Path, str]:
    """The generated artifacts as absolute paths under *root*."""
    return {root / relative: content for relative, content in generate(root).items()}

retired_files

retired_files(root: Path) -> tuple[Path, ...]

The generated workflow files under root this emission does not own, to delete.

Every file in the forge's workflow directory that opens with GENERATED_MARK and is not in this emission is retired: the workflow of a point a package contributed and that went with the package. A file without the mark is a person's and is never touched.

Source code in packages/workshop/src/livery/workshop/_ci_generate.py
def retired_files(root: Path) -> tuple[Path, ...]:
    """The generated workflow files under *root* this emission does not own, to delete.

    Every file in the forge's workflow directory that opens with
    `GENERATED_MARK` and is not in this emission is retired: the
    workflow of a point a package contributed and that went with the
    package. A file without the mark is a person's and is never
    touched.
    """
    found: list[Path] = []
    owned = set(generate(root))
    for directory in (".github/workflows", ".gitea/workflows"):
        folder = root / directory
        if not folder.is_dir():
            continue
        for path in sorted(folder.glob("*.yml")):
            relative = path.relative_to(root).as_posix()
            if relative in owned:
                continue
            try:
                head = path.read_text("utf-8", errors="replace")[: len(GENERATED_MARK)]
            except OSError:
                continue
            if head == GENERATED_MARK:
                found.append(path)
    return tuple(found)