Skip to content

livery.forge._dev

livery.forge._dev

The local forge containers: compose and seeds, as a footman plugin.

fm forge.dev.up starts and seeds Gitea (with its act_runner) and GitLab (with its shell-executor runner) from the compose file shipped in this package; the minted credentials land key by key in the shared env file in the runner's config directory (.repo.shared.env), which the cascade and live test runs read. Every verb is idempotent: re-running it is the recovery procedure, and every seed probes before acting.

This module is the entry point named livery.forge in footman.tasks and footman.builtin: a project that depends on livery-forge directly gets these tasks through footman's project rung, and one that does not is never offered them. Unlike the rest of livery.forge it imports footman and toolroom, which are present by construction: the only loader is footman's own plugin(), so livery-forge still declares no dependency.

fm forge.fixtures.record re-records the conformance cassettes and registers only in forge's own source checkout, where the test suite it runs exists; a wheel install never offers it.

Functions:

Name Description
fixtures_record

Re-record the conformance cassettes from the live containers.

conformance

Run the conformance suites: the cassettes' replay, or live.

dev_up

Start and seed the local forge containers, then their runners.

dev_seed

Seed the running containers; see the per-forge helpers.

dev_down

Stop the local forge containers; --wipe deletes their data too.

dev_restart

Restart one forge's runner, discarding the jobs it was running.

Attributes:

Name Type Description
forge
dev
fixtures

forge module-attribute

forge = group('forge', help='livery.forge development')

dev module-attribute

dev = forge.group('dev', help='Local forge containers (Gitea and GitLab)')

fixtures module-attribute

fixtures = forge.group('fixtures', help='Recorded HTTP fixtures (cassettes)')

fixtures_record

fixtures_record(scenario: Annotated[str, doc('record only this scenario, by its name')] = '', backend: Annotated[str, doc('record only gitea, gitlab, or github')] = '') -> None

Re-record the conformance cassettes from the live containers.

Runs the backend conformance suites against the seeded containers (fm forge.dev.up first) and rewrites the cassettes under forge's tests/cassettes/. Review the diff like code: a changed exchange is a changed contract with the server.

A new scenario needs only its own recording: name it with --scenario (and a backend with --backend) rather than re-recording every exchange, which spends live quota and rewrites cassettes nothing asked to change.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@fixtures.task(name="record")
def fixtures_record(
    scenario: Annotated[str, doc("record only this scenario, by its name")] = "",
    backend: Annotated[str, doc("record only gitea, gitlab, or github")] = "",
) -> None:
    """Re-record the conformance cassettes from the live containers.

    Runs the backend conformance suites against the seeded
    containers (`fm forge.dev.up` first) and rewrites the
    cassettes under forge's tests/cassettes/. Review the diff like
    code: a changed exchange is a changed contract with the
    server.

    A new scenario needs only its own recording: name it with
    ``--scenario`` (and a backend with ``--backend``) rather than
    re-recording every exchange, which spends live quota and
    rewrites cassettes nothing asked to change.
    """
    # The recording switch travels as explicit child env, never an
    # ambient write.
    _run_suites(scenario, backend, {"FORGE_RECORD": "1"}, live=True)

conformance

conformance(scenario: Annotated[str, doc('run only this scenario, by its name')] = '', backend: Annotated[str, doc('run only gitea, gitlab, or github')] = '', live: Annotated[bool, doc('against the seeded containers, the cassettes untouched')] = False) -> None

Run the conformance suites: the cassettes' replay, or live.

Replay is the gate's own run, with no network and no credential. --live runs against the seeded containers (fm forge.dev.up first) and rewrites nothing; a local backend that is not up is refused by name before its suite starts, and GitHub's live arm reads the e2e organisation's credential the way the recorder does.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@forge.task(name="conformance")
def conformance(
    scenario: Annotated[str, doc("run only this scenario, by its name")] = "",
    backend: Annotated[str, doc("run only gitea, gitlab, or github")] = "",
    live: Annotated[
        bool, doc("against the seeded containers, the cassettes untouched")
    ] = False,
) -> None:
    """Run the conformance suites: the cassettes' replay, or live.

    Replay is the gate's own run, with no network and no
    credential. ``--live`` runs against the seeded containers
    (`fm forge.dev.up` first) and rewrites nothing; a local
    backend that is not up is refused by name before its suite
    starts, and GitHub's live arm reads the e2e organisation's
    credential the way the recorder does.
    """
    switch = {"FORGE_LIVE": "1"} if live else {}
    _run_suites(scenario, backend, switch, live=live)

dev_up

dev_up(profile: Annotated[str, doc('which forges: gitea, gitlab, or all')] = 'all', with_docker: Annotated[bool, doc("mount the host's docker socket into the runners")] = False) -> None

Start and seed the local forge containers, then their runners.

Idempotent: re-running it is the recovery procedure. Each runner starts after its seed because the registration token is minted by the seed. GitLab is long-lived and takes minutes on first boot. --with-docker mounts the host's docker socket into both runners, for the jobs that build images: cibuildwheel's build containers and the container publish seam. Without it the runners have no docker, and a seam declared none skips green; the flag's state is the runners' own, so an up that changes it recreates them.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@dev.task(name="up")
def dev_up(
    profile: Annotated[str, doc("which forges: gitea, gitlab, or all")] = "all",
    with_docker: Annotated[
        bool, doc("mount the host's docker socket into the runners")
    ] = False,
) -> None:
    """Start and seed the local forge containers, then their runners.

    Idempotent: re-running it is the recovery procedure. Each runner
    starts after its seed because the registration token is minted by
    the seed. GitLab is long-lived and takes minutes on first boot.
    ``--with-docker`` mounts the host's docker socket into both
    runners, for the jobs that build images: cibuildwheel's build
    containers and the container publish seam. Without it the runners
    have no docker, and a seam declared none skips green; the flag's
    state is the runners' own, so an ``up`` that changes it recreates
    them.
    """
    if profile not in ("gitea", "gitlab", "all"):
        fail(f"unknown profile {profile}: use gitea, gitlab, or all")
    if profile in ("gitea", "all"):
        _compose("--profile", "gitea", "up", "-d", "--wait", "gitea")
        _seed_gitea()
        token = _read_env(_rig_record_path()).get("GITEA_RUNNER_TOKEN", "")
        # --build: the runner image is built from runner.Dockerfile, so
        # a changed toolchain line rebuilds it here instead of running
        # on the stale image under the pinned tag.
        _compose(
            "--profile",
            "gitea",
            "--profile",
            "gitea-runner",
            "up",
            "-d",
            "--build",
            "act_runner",
            env={"GITEA_RUNNER_TOKEN": token},
            with_docker=with_docker,
        )
        print(f"  gitea: {_GITEA_URL}  credentials: {_credentials()}")
    if profile in ("gitlab", "all"):
        _compose("--profile", "gitlab", "up", "-d", "--wait", "gitlab")
        _seed_gitlab()
        # --build, as for act_runner: the two services share the image.
        _compose(
            "--profile",
            "gitlab",
            "--profile",
            "gitlab-runner",
            "up",
            "-d",
            "--build",
            "gitlab-runner",
            with_docker=with_docker,
        )
        _register_gitlab_runner()
        print(f"  gitlab: {_GITLAB_URL}  credentials: {_credentials()}")
    if with_docker:
        print("  runners: the host's docker socket is mounted")

dev_seed

dev_seed(profile: Annotated[str, doc('which forges: gitea, gitlab, or all')] = 'all') -> None

Seed the running containers; see the per-forge helpers.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@dev.task(name="seed")
def dev_seed(
    profile: Annotated[str, doc("which forges: gitea, gitlab, or all")] = "all",
) -> None:
    """Seed the running containers; see the per-forge helpers."""
    if profile in ("gitea", "all"):
        _seed_gitea()
    if profile in ("gitlab", "all"):
        _seed_gitlab()

dev_down

dev_down(profile: Annotated[str, doc('which forges: gitea, gitlab, or all')] = 'all', wipe: Annotated[bool, doc('also delete the data volumes')] = False) -> None

Stop the local forge containers; --wipe deletes their data too.

--profile stops one forge and its runner and leaves the other up, matching up. A wipe of one forge deletes its volumes alone; the shared env file and the containers' own record go only when every forge is wiped, since each carries the other forge's credentials too.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@dev.task(name="down")
def dev_down(
    profile: Annotated[str, doc("which forges: gitea, gitlab, or all")] = "all",
    wipe: Annotated[bool, doc("also delete the data volumes")] = False,
) -> None:
    """Stop the local forge containers; `--wipe` deletes their data too.

    ``--profile`` stops one forge and its runner and leaves the other
    up, matching ``up``. A wipe of one forge deletes its volumes
    alone; the shared env file and the containers' own record go only
    when every forge is wiped, since each carries the other forge's
    credentials too.
    """
    forges = _forges(profile)
    if wipe and profile == "all":
        _dev_env_path().unlink(missing_ok=True)
        _rig_record_path().unlink(missing_ok=True)
    if profile == "all":
        args = []
        for names, _runner in _FORGE_PROFILES.values():
            for name in names:
                args += ["--profile", name]
        args.append("down")
        if wipe:
            args.append("--volumes")
        _compose(*args)
        return
    for forge_kind in forges:
        names, runner = _FORGE_PROFILES[forge_kind]
        args = []
        for name in names:
            args += ["--profile", name]
        # One forge's services alone: `down` would take the whole
        # project, so its containers stop and are removed by name.
        services = [forge_kind, runner]
        _compose(*args, "stop", *services)
        _compose(*args, "rm", "-f", *(["-v"] if wipe else []), *services)
        print(f"  {forge_kind}: stopped" + (", volumes deleted" if wipe else ""))

dev_restart

dev_restart(profile: Annotated[str, doc("which forges' runners: gitea, gitlab, or all")] = 'all') -> None

Restart one forge's runner, discarding the jobs it was running.

The recovery for a runner grinding the runs a dead pass left behind: the runner container restarts, its jobs die with it, and it registers again with the same configuration. The forge itself stays up.

Source code in packages/forge/src/livery/forge/_dev/__init__.py
@dev.task(name="restart")
def dev_restart(
    profile: Annotated[
        str, doc("which forges' runners: gitea, gitlab, or all")
    ] = "all",
) -> None:
    """Restart one forge's runner, discarding the jobs it was running.

    The recovery for a runner grinding the runs a dead pass left
    behind: the runner container restarts, its jobs die with it, and
    it registers again with the same configuration. The forge itself
    stays up.
    """
    for forge_kind in _forges(profile):
        names, runner = _FORGE_PROFILES[forge_kind]
        args = []
        for name in names:
            args += ["--profile", name]
        _compose(*args, "restart", runner)
        print(f"  {forge_kind}: runner {runner} restarted")