livery.workshop._ci_tasks¶
livery.workshop._ci_tasks ¶
fm status and the ci group.
status says where the current branch's pull request stands and
exits that state's code (0 while nothing is wrong); --watch
follows instead of reading once. The ci group acts on the head
commit's runs: ci.rerun re-runs the failed jobs, ci.cancel
cancels what is still moving (the relief for a wedged queue),
ci.status says where the head commit's runs stand and exits that
state's code, so a script can wait on main after a merge, and
ci.logs prints the job logs, the one read that stays here so
logs reach an agent through fm; both read the newest run of a point
instead under --point, which is how the nightly's verdict reaches
a person. ci.dispatch starts a point that has a dispatch entry
(the gate, the nightly) and follows it to its verdict. ci.run
runs one job of a point
(livery.workshop._points), the one verb the emitted shells call;
ci.verdict is the gate job's judgement of the jobs it needs.
ci.timings prints the timing rows the gate writes on
that store (livery.workshop._metrics), ci.balance reads the
same rows to predict each platform's wall at one to several shards
and propose the counts (livery.workshop._balance), and
ci.footprint sums the same rows into runner-minutes per runner
label, priced where GitHub would bill them
(livery.workshop._footprint); the hidden
ci.metrics.collect is the gate job's writer ci.run schedules,
the hidden ci.fold folds each platform's shards into one leg
before the judges read, and the hidden ci.leg is each check leg's
one write of its row.
Functions:
| Name | Description |
|---|---|
remember_mounted_tasks |
Keep this run's merged task tree for the declared points' task check. |
status_flow |
Print where the branch stands; return that state's exit code. |
status |
Say where the branch's pull request stands; exit that state's code. |
rerun_flow |
Re-run the failed runs that hold this branch's verdict. |
ci_rerun |
Re-run the head commit's failed runs. |
cancel_flow |
Cancel the head commit's unfinished runs. |
ci_cancel |
Cancel the head commit's unfinished runs. |
cancel_superseded_runs |
Cancel the runs still moving for sha, a commit a newer push has superseded. |
point_runs |
The newest limit runs of point's workflow, whatever commit they checked. |
follow_run |
Follow run of point to its verdict; return that state's exit. |
remote_head |
The commit branch ref names on origin; empty for a tag or a missing branch. |
own_runs |
The runs among runs that may be the one a dispatch on ref started. |
dispatch_flow |
Start point on ref by hand; follow it to its verdict; return the exit. |
footman_prog |
The runner's name, for a remedy in a message. |
ci_dispatch |
Start a point on the forge by hand and follow it to its verdict. |
runs_state |
The one word for runs together and its exit: green 0, pending 18, red 13. |
runs_status_flow |
Print the head commit's runs and their state; return that state's exit. |
ci_status |
Say where the head commit's runs stand; exit that state's code. |
failure_lines |
The lines of log that name a failure, the first limit of them. |
logs_flow |
Print the head commit's job logs, failed jobs first and by default. |
ci_logs |
Print the head commit's job logs, failed jobs by default. |
ci_run |
Run one job of a point: every task scheduled there, in order. |
sweep_tool_store |
Sweep the tool store on a GitHub job, before the post-job save; the note. |
verdict_flow |
The red jobs of this run among needs, and any other red job; empty is green. |
ci_verdict |
Judge the run: green when every needed job succeeded, red naming the rest. |
verified_stamp_flow |
Stamp the run's tree when every check leg ran the full gate; print why not. |
ci_verified_stamp |
Record this run's tree as proved green, for the runs that share it. |
leg_flow |
Put this leg's row and its spool on its per-run ref; red when the write fails. |
ci_leg |
Put this check leg's row and the files its entries left on its ref, in one write. |
fold_flow |
Fold each platform's shards on the run's refs into one leg; print every line. |
ci_fold |
Fold each platform's shards into one check leg on the run's refs. |
metrics_collect_flow |
Collect the run's rows into the metrics series; print every line. |
ci_metrics_collect |
Join the legs' timing rows with the forge's times into the run's file. |
drop_flow |
Drop the run's per-run refs once every half is in; print every line. |
ci_metrics_drop |
Drop the run's per-run refs, once every job that put a half is green. |
record_flow |
Put this job's half from its box, collect the run's row, drop when last. |
ci_metrics_record |
Record this job's run: its half, the run's row, the refs dropped when last. |
ci_profile |
Write one CI run as one timeline, to open at ui.perfetto.dev. |
timings_flow |
Print the rendered timings, then the speed marks beside the newest run. |
ci_timings |
Print the CI timings: per job and metric the latest, p50, p90, and the movers. |
balance_flow |
Print the balancer's window line, its tables and its proposal; write writes. |
ci_balance |
Predict each check platform's wall at one to several shards; propose the counts. |
footprint_flow |
Print the window's runner-minutes by runner label; price them where GitHub would. |
ci_footprint |
Sum the window's runner-minutes by runner label; price them where GitHub would. |
Attributes:
| Name | Type | Description |
|---|---|---|
ci |
|
|
RECENT_RUNS |
|
|
verified |
|
|
metrics |
|
|
profile |
|
verified
module-attribute
¶
verified = ci.group('verified', help='The trees a green gate proved', hidden=True)
metrics
module-attribute
¶
metrics = ci.group('metrics', help='The timing rows CI writes', hidden=True)
remember_mounted_tasks ¶
remember_mounted_tasks(inv: Invocation) -> None
Keep this run's merged task tree for the declared points' task check.
A [[ci.point]] names a task some extension mounts; the check reads
the tree discovery merged for this invocation, which the
module-level registry no longer holds by the time a task runs.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
status_flow ¶
status_flow(repo: Repository, root: Path) -> int
Print where the branch stands; return that state's exit code.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
status ¶
status(watch: Annotated[bool, doc('follow until it lands or needs a person')] = False, workflow: Annotated[bool, doc('the reserved workflows instead')] = False, interval: Annotated[int, doc('watch poll seconds')] = 15, timeout: Annotated[int, doc('watch deadline seconds')] = 1800) -> None
Say where the branch's pull request stands; exit that state's code.
Exit 0 covers merged, in flight, and no pull request; each blocker
state keeps its own stable code (see livery.workshop._verdict), and
the printed sentence always says what to do next. --watch
follows instead of reading once: the same classification, polled
until the branch lands or a person is needed. --workflow
reads the reserved workflows instead, one line each with its
state, author, and, for a mid-publish release, the members whose
receipt tag is already cut.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
rerun_flow ¶
rerun_flow(repo: Repository, root: Path, *, failed_only: bool = True) -> None
Re-run the failed runs that hold this branch's verdict.
The verdict is each workflow's newest run on a commit this branch contains. The head commit's runs are the common case, but a workflow triggered on an earlier commit (a merged release squash, a path-filtered job) keeps its verdict until it re-runs, so scoping to the head sha alone would miss it. With failed_only the failed jobs alone rerun, except where the contract splits a check leg into shards (livery.workshop._points.sharded_legs): a rerun of one shard partitions afresh and the gate job's fold would read one platform from two attempts, so the whole run reruns and one line says why. Each rerun is read back: a forge that quietly ignores the request is named, never reported as re-running. Off main, a run on a commit main already contains is main's verdict (a scheduled nightly, a merge-point run): it is named and left for a re-run from main.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | |
ci_rerun ¶
Re-run the head commit's failed runs.
The failed jobs alone by default; the whole run under
--no-failed-only, and whenever the contract splits a check leg
into shards, since a rerun of one shard partitions the items
afresh and the gate job's fold refuses shards of two attempts.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
cancel_flow ¶
cancel_flow(repo: Repository, root: Path, *, force: bool = False) -> None
Cancel the head commit's unfinished runs.
The relief for a wedged queue; force reaches the runs a plain
cancel cannot, where the forge grants the capability.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_cancel ¶
Cancel the head commit's unfinished runs.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
cancel_superseded_runs ¶
cancel_superseded_runs(repo: Repository, sha: str) -> list[str]
Cancel the runs still moving for sha, a commit a newer push has superseded.
A push that moves a branch's head leaves the old head's runs running with nothing left to read them, and on a shared runner they delay the new head's. The cancel is best effort: a run the forge refuses to cancel (already terminal, cancelling) is named and left. Returns one line per run touched.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
point_runs ¶
point_runs(repo: Repository, point: str, root: Path | None = None, *, limit: int = RECENT_RUNS) -> tuple[Run, ...]
The newest limit runs of point's workflow, whatever commit they checked.
Newest first. Asked of the workflow's own listing for each of the point's events, so a forge with a long history answers with one page. The workflow's file name is compared here as well (GitHub lists the path, Gitea the file; the basename is the comparison). A forge that names no workflow on a run (GitLab) answers by event alone.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
follow_run ¶
follow_run(repo: Repository, point: str, run: Run, *, interval: float = 15, timeout: float = 1800) -> int
Follow run of point to its verdict; return that state's exit.
Progress prints on state changes and every minute. Green is 0; red is 13 with the red jobs named; a wait that runs out is 14; a forge unreachable past the transient budget is 15.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
remote_head ¶
The commit branch ref names on origin; empty for a tag or a missing branch.
The commit a dispatched run checks out, read just before the dispatch. A tag names one commit for good, so only a branch is read. An unreachable origin refuses, naming git's words.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
own_runs ¶
own_runs(runs: tuple[Run, ...], *, seen: set[int], started: int | None, ref: str, head: str) -> list[Run]
The runs among runs that may be the one a dispatch on ref started.
started is the id the forge's answer named, and settles it. Without one, a run qualifies when it is a dispatched run, is not in seen (the listing read just before the dispatch), checked out ref, and, when head names a commit, checked out that commit. A run of another ref never qualifies, however new.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
dispatch_flow ¶
dispatch_flow(repo: Repository, *, point: str, ref: str, head: str = '', follow: bool = True, interval: float = 15, timeout: float = 1800, register_timeout: float = 60, only: str = '') -> int
Start point on ref by hand; follow it to its verdict; return the exit.
Refuses a point without a dispatch entry, naming what starts it instead. only names the scheduled tasks the run takes, comma-separated, for a point that takes the input: a rehearsal names the loop alone. A name the point does not run, or only on a point without the input, refuses before anything is dispatched.
The dispatch is confirmed by its own run: the one the forge's answer names, or else the one dispatched run of ref that was not listed before the dispatch and, when head is given, checked out that commit, the one ref named just before. A run of another ref is never followed. Two or more such runs refuse, naming each, since the listing cannot tell which one this dispatch started. None within register_timeout is reported with the verb that reads the point later and the dispatched runs of other refs or commits that did appear, exit 14. Without follow the run is named and the exit is 18 while it moves.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 | |
ci_dispatch ¶
ci_dispatch(point: Annotated[str, doc('the point to start: gate, nightly, or one a package contributes')] = 'nightly', ref: Annotated[str, doc('the branch or tag the run checks out')] = 'main', follow: Annotated[bool, doc("wait for the run's verdict")] = True, interval: Annotated[int, doc('poll seconds')] = 15, timeout: Annotated[int, doc('deadline seconds for the verdict')] = 1800, only: Annotated[str, doc('the scheduled tasks the run takes, comma-separated, for the nightly: ci.e2e rehearses the loop alone; empty runs everything')] = '') -> None
Start a point on the forge by hand and follow it to its verdict.
The gate and the nightly carry a dispatch entry. A dispatched
gate pays the full gate on ref, since the check verb narrows on
a pull request alone, and its stamp writes a full row for the
tree it proved; the nightly's run waits for nobody, and this verb
starts the same run now, so a failure only the nightly meets (a
floor Python, a release's verification) is reproduced on demand.
The run followed is the dispatch's own: the one the forge names,
or the one dispatched run of ref, at the commit origin names for
it, that appeared after the dispatch. Two such runs refuse, naming
both. Exits green 0, red 13 with the red jobs named, a run that
never registered or a wait that runs out 14, a forge unreachable
for five polls in a row 15, and, with --no-follow, 18 while
the run moves. The merge point runs on a push alone, and the
release wave is the merge point's to dispatch.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
runs_state ¶
The one word for runs together and its exit: green 0, pending 18, red 13.
No run at all is pending: the forge may not have registered the push yet, and a script waiting on it keeps waiting. A run still moving is pending whatever the others concluded. Red is any run that completed with a conclusion that is not green.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
runs_status_flow ¶
runs_status_flow(repo: Repository, root: Path, *, wait: bool = False, interval: float = 15, timeout: float = 1800, point: str = '') -> int
Print the head commit's runs and their state; return that state's exit.
One line per run, workflow, status or conclusion, event, commit, and page, then the word for all of them. With point the one run read is the newest of that point's workflow, whatever commit it checked: the nightly's verdict, which no commit of a branch carries. With wait the read repeats every interval seconds while the state is pending, until timeout, which exits 14; a transport error under wait is a retry, and a run of them that reaches the budget exits 15. Without wait an unreadable forge is named in one line and exits 15 at once.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 | |
ci_status ¶
ci_status(wait: Annotated[bool, doc('poll until the runs are no longer pending')] = False, interval: Annotated[int, doc('poll seconds under --wait')] = 15, timeout: Annotated[int, doc('deadline seconds under --wait')] = 1800, point: Annotated[str, doc('read the newest run of this point instead')] = '') -> None
Say where the head commit's runs stand; exit that state's code.
Green exits 0, red 13, pending 18, a wait that runs out 14, and
a forge unreachable for five polls in a row under the wait 15,
so a script can ask whether main's push has finished after a
merge. The head is the pull request's when the branch has one,
else the local HEAD, so on main after a pull it is the merge.
--point=nightly reads the newest nightly run instead, by
workflow rather than by commit, so a failure only the nightly
meets reaches a person here.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
failure_lines ¶
The lines of log that name a failure, the first limit of them.
A long leg buries pytest's FAILED summary hundreds of lines
above its end, behind the coverage table, so a tail alone shows
the exit code and not the test.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
logs_flow ¶
logs_flow(repo: Repository, root: Path, *, lines: int = 80, failed_only: bool = True, point: str = '') -> None
Print the head commit's job logs, failed jobs first and by default.
The tail of each log, newest run first, so a red branch explains itself without leaving the terminal; the log's failure lines (livery.workshop._ci_tasks.failure_lines) come first when the tail does not reach them. With point the one run read is the newest of that point's workflow.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_logs ¶
ci_logs(lines: Annotated[int, doc('log lines per job, from the tail')] = 80, failed_only: Annotated[bool, doc('only jobs that did not succeed')] = True, point: Annotated[str, doc('read the newest run of this point instead')] = '') -> None
Print the head commit's job logs, failed jobs by default.
--point=nightly prints the newest nightly run's logs instead.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_run ¶
ci_run(*, point: Annotated[str, doc('the point: gate, merge, nightly, or release')], job: Annotated[str, doc("the point's job this runner executes")], os: Annotated[str, doc('the matrix runner label, on a matrix job')] = '', python: Annotated[str, doc('the matrix python, on a matrix job')] = '', shard: Annotated[str, doc("the leg's shard, <i>of<n>, on a check leg the contract splits")] = '') -> None
Run one job of a point: every task scheduled there, in order.
The one verb the emitted workflows call, once per job. What the
job does is data: the workshop's builtin schedule plus the
contract's [[ci.schedule]] entries. A push to main promotes
the gate to the merge point, so the shell spells no decision. On
a check leg the contract splits, --shard=2of4 names the shard
this job runs as: it ends the leg's label and the job's display
name, and the walk runs that shard's share; without it the job
runs as one shard of one. A person may run a job by hand; the
tasks that only CI may do refuse or fail open on their own.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
sweep_tool_store ¶
Sweep the tool store on a GitHub job, before the post-job save; the note.
A tool's archive stays in the store as an object once its tree is extracted and named, and nothing reaches it again: the tree is what a pinned version runs from. The workflow saves the whole store, so those objects would ride in every archive and cost every restore. Off a GitHub job nothing runs and the note is empty; on Gitea's runner, which sets the same variable, shares one store across its jobs and saves none, the store is kept whole and the note says so. A failed sweep is named and never decides the job.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
verdict_flow ¶
The red jobs of this run among needs, and any other red job; empty is green.
A needed job is matched by name or, for a matrix job, by its
display name's prefix (check (ubuntu-latest, 3.14) answers to
check). A needed job the forge does not list at all counts as
red: the verdict never passes on a job it could not see.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_verdict ¶
ci_verdict(*, needs: Annotated[str, doc('the jobs this verdict requires, comma-separated')] = '') -> None
Judge the run: green when every needed job succeeded, red naming the rest.
Runs in the gate job, the one required context, after the jobs it needs have completed. It asks the forge for the run's jobs, so the YAML carries no expression over them; a job it cannot see is red, never assumed.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
verified_stamp_flow ¶
verified_stamp_flow(root: Path) -> None
Stamp the run's tree when every check leg ran the full gate; print why not.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_verified_stamp ¶
Record this run's tree as proved green, for the runs that share it.
Runs in the gate job after the verdict, so only a green run reaches it. Every check leg's metrics row must say it ran the full gate; a narrowed leg leaves the tree unstamped, and a later run of the same tree pays the gate. Fails open loudly: every reason is printed and the exit stays 0.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
leg_flow ¶
Put this leg's row and its spool on its per-run ref; red when the write fails.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_leg ¶
ci_leg(*, job: Annotated[str, doc("the job's name as the forge lists it")] = '', trace: Annotated[Path, doc('the trace the gate wrote')] = Path(TRACE)) -> None
Put this check leg's row and the files its entries left on its ref, in one write.
The check leg's last entry. The row is the leg's timing half, read
from the trace the profiled gate wrote, with the scope the gate
ran; beside it go the files the leg's other entries left in its
spool, .workshop/leg/, each under its own name. A trace that
cannot be read prints its reason and the write goes on without
the row. A write that fails is red.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
fold_flow ¶
fold_flow(root: Path) -> None
Fold each platform's shards on the run's refs into one leg; print every line.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_fold ¶
Fold each platform's shards into one check leg on the run's refs.
Runs in the gate job before the judges, the collect, the verdict and the stamp read the run's refs. A platform whose check leg ran as several shards has one ref per shard; the fold proves the shards are one leg's work (one scope, one item set from one durations row, every item in exactly one shard, every shard the matrix produces present) and puts one ref under the platform leg's key, the timing sums added and every other file folded by the extension that leaves it, then drops the shards' refs. A platform whose shards disagree, or one of whose shards left no ref, is red naming the platform, the shards and what differs. A run with no sharded platform says so and changes nothing.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
metrics_collect_flow ¶
metrics_collect_flow(root: Path, repo: Repository) -> None
Collect the run's rows into the metrics series; print every line.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_metrics_collect ¶
Join the legs' timing rows with the forge's times into the run's file.
Runs in the gate job before its verdict. Reads the per-run refs
the legs wrote, asks the forge for the run's jobs and their
steps, and puts the run's file on the metrics series under its
window. The per-run refs stay for ci.metrics.drop, the job's
last entry, so a red verdict leaves them for the forge's re-run
of the job, which runs without its legs. Fails open loudly: every
reason is printed and the exit stays 0.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
drop_flow ¶
drop_flow(root: Path, repo: Repository, *, point: str, job: str) -> None
Drop the run's per-run refs once every half is in; print every line.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_metrics_drop ¶
ci_metrics_drop(*, point: Annotated[str, doc("the point whose jobs put the run's halves")] = '', job: Annotated[str, doc("this job's name as the forge lists it")] = '') -> None
Drop the run's per-run refs, once every job that put a half is green.
The last entry of a job that collected the run's row, after its verdict: this job is green when it runs. The refs stay while another job that puts a half (a check leg, or a sibling job of a point with no gate job) has not completed green, or any completed job is red, so a re-run finds what the legs put and the last of a point's collecting jobs is the one that drops. Fails open loudly: every reason is printed and the exit stays 0.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
record_flow ¶
record_flow(root: Path, repo: Repository, *, point: str, job: str) -> None
Put this job's half from its box, collect the run's row, drop when last.
Every line is printed and none is a verdict: the row is a record of what the job did, and a job with no gate job to judge it stays green whatever its record could not do. The three steps share one listing of the store, taken here: the put records its ref in it, so the collect and the drop after it see the half it just put.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_metrics_record ¶
ci_metrics_record(*, point: Annotated[str, doc('the point this job belongs to')] = '', job: Annotated[str, doc("this job's name as the forge lists it")] = '') -> None
Record this job's run: its half, the run's row, the refs dropped when last.
The last entry of every job of a point with no gate job (the nightly, the release, a point a package contributes). The half is the union of the traces the job's entries left in its profile box, put on the job's per-run ref; the collect then writes the run's row from every half present, so each job's write carries the jobs before it; the drop takes the refs once every job of the point has completed green. Fails open loudly: every reason is printed and the exit stays 0.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_profile ¶
ci_profile(*, run: Annotated[str, doc("the run's id; the newest for HEAD by default")] = '', from_: Annotated[str, doc('walk every run about this commit, and what its merge caused')] = '', into: Annotated[str, doc("where the file lands; the contract's own by default")] = '') -> None
Write one CI run as one timeline, to open at ui.perfetto.dev.
Every job of the run is a track at the forge's own times, its steps inside it, and each leg that kept a trace brings its own tasks, steps and tests, laid on the run's clock by the origin each side recorded. This is what the legs' traces are kept for, and what the window bounds.
--from=<commit> writes the chain instead: every run about that
commit, and the runs of the commit its merge produced. A release is
two commits and one hop, so the pull request's run, the base's own
run and the wave land in one file. Any commit-ish a checkout can
resolve names it, HEAD included.
Refuses when no file could be written, naming why: a person asked for one. A run whose traces have aged out of the window still assembles from the forge's skeleton alone, and says which legs brought nothing.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
timings_flow ¶
Print the rendered timings, then the speed marks beside the newest run.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_timings ¶
ci_timings(since: Annotated[int, doc('the recent runs the movers judge')] = 1, base: Annotated[int, doc('the runs before them the movers compare against')] = 20) -> None
Print the CI timings: per job and metric the latest, p50, p90, and the movers.
Reads the metrics series the gate job writes; CI is its only writer, a local run reads. Per job, every metric's latest value and its median and ninetieth percentile over the series' window; a platform that ran as shards is one job, its folded row, with a line per shard under it giving the shard's wall and queue times from the newest run. Then the biggest movers: the recent runs' median against the base runs' median. Then the speed marks, each package's mark on each leg beside the newest run's time.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
balance_flow ¶
Print the balancer's window line, its tables and its proposal; write writes.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_balance ¶
ci_balance(max_: Annotated[int, doc('the largest shard count a platform may take; 0 reads [ci] shards-max, 4 when the contract is silent')] = 0, write: Annotated[bool, doc('rewrite [ci] shards and [ci] pull-request-shards when due')] = False, submit: Annotated[bool, doc("write, commit on the day's branch and open its pull request, unarmed (implies --write)")] = False) -> None
Predict each check platform's wall at one to several shards; propose the counts.
Reads the metrics series the gate job writes; CI is its only
writer, a local run reads. Per platform, a runner and a Python,
the newest ten rows whose check jobs ran the full gate and
succeeded give the medians of four measures: F, the setup and
teardown the forge timed around the call; O, the summed wall of
the gate steps that are not test steps, which the first shard
alone runs; S, the summed test time over every package; and p,
the parallelism the test step reached, S over its wall. The
shards of a platform fold into one reading. The first shard's
slice is lighter by the tests O holds back, so the wall at n
shards is predicted as F + max(O, (S / p + O) / n) and the runner
seconds as about n F + S / p + O; the table prints
both for every count up to the cap, [ci] shards-max or
--max under it.
The proposal: the slowest platform, the largest wall at one
shard, takes the largest count whose every added shard saved at
least F; every other platform takes the smallest count whose
wall is within 15% of the slowest platform's, or the cap, named.
The pull request counts follow the same rule over
[ci] pull-request-runners when that list is shorter than
[ci] runners. The proposal prints as the TOML [ci] shards
and [ci] pull-request-shards would hold, with the predicted
wall of the slowest leg beside its wall at one shard. A platform
with fewer than three such rows keeps its count and is named. A
store that cannot be read prints why and proposes nothing.
Without a flag the verb changes nothing. --write rewrites the
two keys in the root workshop.toml when a count differs from
the contract's and the predicted wall at the proposed counts
differs from the wall at the contract's counts by more than 10%,
so a count does not move back and forth; every comment and every
other key stay, a count of one is left out of a table, a table
that would be empty is removed, and [ci] shards-max is read
and never written. It prints what each key becomes, or why nothing
was written: no platform with enough rows, no count changed, or a
wall that moved less. The workflows follow at the next fm sync,
which the last line says. --submit writes the same change on
the day's branch, chore/balance-<date>, renders the workflows,
commits it as chore(ci): the check legs run as <counts> and
submits it unarmed, for a person to merge; it runs from origin's
default branch alone and says so otherwise, and a day whose branch
origin already holds at these counts submits nothing and says so.
The nightly runs it once a day. A count can also be set by hand.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 | |
footprint_flow ¶
footprint_flow(root: Path, repo: Repository, *, since: int) -> None
Print the window's runner-minutes by runner label; price them where GitHub would.
Fails when the window holds no row, naming what writes one.
Source code in packages/workshop/src/livery/workshop/_ci_tasks.py
ci_footprint ¶
ci_footprint(since: Annotated[int, doc('the newest runs read; 0 reads the whole window')] = 0) -> None
Sum the window's runner-minutes by runner label; price them where GitHub would.
Reads the metrics series the gate job writes; CI is its only
writer, a local run reads. Every job of every run in the window,
or of the newest --since runs, is counted on one runner label:
a check leg on the runner its job name lists, every other job (the
gate job, the docs build, the release jobs) on the first runner
[ci] runners names, where the workflow places them. Per label
and kind the jobs and the minutes, then the total and the minutes
per 30 days from the window's span. A job without a wall time,
still running when the gate job collected or never started, is
counted apart and priced as nothing.
On GitHub, when the repository is public, the same minutes are priced at GitHub's rates for the standard runners of a private repository, by the class the label names (linux, windows, macos), with the total, the USD per 30 days and the source page: a public repository is not billed for them, and the price says what the matrix would cost one that is. On another forge, or on a private GitHub repository, nothing is priced.
Fails when the window holds no row: the gate job of a run on the forge writes one.