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; |
dev_restart |
Restart one forge's runner, discarding the jobs it was running. |
Attributes:
| Name | Type | Description |
|---|---|---|
forge |
|
|
dev |
|
|
fixtures |
|
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
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
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_seed ¶
Seed the running containers; see the per-forge helpers.
Source code in packages/forge/src/livery/forge/_dev/__init__.py
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_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.