1"""The CI workflow renderers: the declared points, in each forge's words.
3Workflow files are mechanical forge knowledge, emitted here from the
4workspace contract (``workshop.toml``) and the derived Python matrix,
5written as managed generated artifacts, and the drift check compares
6the committed files against these same pure functions, offline.
7Change an emitter, run ``fm sync``, and every kind's files move
8together.
10Every job enters through the emitted ``setup.sh`` (the entry
11contract: uv at the lock's pin, the venv synced against the lock,
12the emission persisted) and then calls the runner bare: no ``uv run``
13anywhere in a rendered workflow.
15The release workflows are the merge-triggered train: publishing runs
16where the release PR's squash lands, and the receipt tags are cut by
17``fm workflow.release.publish`` after the index confirms each
18member, so a tag is a receipt, never a trigger.
19"""
21from __future__ import annotations
23import json
24from collections.abc import Mapping, Sequence
25from pathlib import Path
26from typing import TYPE_CHECKING, Any, cast
28import livery.footman as footman
29from livery.workshop._contract import load_contract
30from livery.workshop._points import (
31 EVENT_NAMES,
32 Job,
33 Point,
34 emitted_points,
35 job_installs,
36 job_runners,
37 job_seams,
38 points,
39 pull_request_listed,
40 pull_request_runners,
41 shard_counts,
42)
43from livery.workshop._pythons import gate_pythons, python_matrix
44from livery.workshop._shard import Shard
46if TYPE_CHECKING:
47 from livery.workshop._composition import Lookup
50def _pinned(repo: str, commit: str, version: str) -> str:
51 """One ``uses:`` value: *repo* at *commit*, with the *version* the commit is."""
52 return f"{repo}@{commit} # {version}"
55#: The actions the emitted jobs use, by forge, each pinned to a commit
56#: with its version beside it. Keyed by forge because each forge's
57#: runners prove their own majors: this repository's CI proves
58#: GitHub's, the loop proves Gitea's on the v4 line. A bump moves with
59#: its proof. The pin table and nothing else says which commit a job
60#: runs, so a rendered ``uses:`` never names a moving tag.
61ACTIONS: dict[str, dict[str, str]] = {
62 "github": {
63 "checkout": _pinned(
64 "actions/checkout", "3d3c42e5aac5ba805825da76410c181273ba90b1", "v7.0.1"
65 ),
66 "upload": _pinned(
67 "actions/upload-artifact",
68 "043fb46d1a93c77aae656e7c1c64a875d1fc6a0a",
69 "v7.0.1",
70 ),
71 "download": _pinned(
72 "actions/download-artifact",
73 "3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c",
74 "v8.0.1",
75 ),
76 "setup-uv": _pinned(
77 "astral-sh/setup-uv", "20cfd1bf945f4377ade1205e4dbc17946fc9a30d", "v10.0.1"
78 ),
79 # The cache action the jobs restore and save through: the tool
80 # store, uv's cache and conan's home, each keyed by its lock
81 # with a prefix fallback.
82 "cache": _pinned(
83 "actions/cache", "0057852bfaa89a56745cba8c7296529d2fc39830", "v4.3.0"
84 ),
85 "upload-pages": _pinned(
86 "actions/upload-pages-artifact",
87 "7b1f4a764d45c48632c6b24a0339c27f5614fb0b",
88 "v4.0.0",
89 ),
90 "deploy-pages": _pinned(
91 "actions/deploy-pages", "d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e", "v4.0.5"
92 ),
93 },
94 "gitea": {
95 "checkout": _pinned(
96 "actions/checkout", "11d5960a326750d5838078e36cf38b85af677262", "v4.4.0"
97 ),
98 "upload": _pinned(
99 "actions/upload-artifact",
100 "ea165f8d65b6e75b540449e92b4886f43607fa02",
101 "v4.6.2",
102 ),
103 "download": _pinned(
104 "actions/download-artifact",
105 "d3f86a106a0bac45b974a628896c90dbdf5c8093",
106 "v4.3.0",
107 ),
108 },
109}
110#: The tool store's home on a GitHub job: the data directory the entry
111#: places under the runner's temp, the working drive, and the store as
112#: its `toolroom`. Literal here because the step runs before any verb
113#: can: the venv it would need is what the entry step makes.
114STORE_HOME = "${{ runner.temp }}/footman/toolroom"
115#: Where a GitHub job keeps conan's home: the working drive, the job's
116#: own, the path conan's declared CONAN_HOME, ``{place}/conan``, takes
117#: on a GitHub job, where the entry and `fm env.emit --github` place it
118#: under the runner's temp, so the cache step and every conan the job
119#: runs agree on one directory.
120CONAN_HOME = "${{ runner.temp }}/conan"
123def _facts(root: Path, everything: tuple[Point, ...] | None = None) -> dict[str, Any]:
124 """What the emitters read: the contract's CI facts, matrix derived.
126 Runners, the shards per runner, the required context, and the
127 forge kind come from ``workshop.toml``; the Python matrix from the root
128 ``pyproject.toml``'s floor and the workshop's newest supported
129 minor; the uv pin from the lock; what a job installs, where it
130 deploys and the runners it fans out to from the functions the job
131 names, over *everything*, the points the files render, *root*'s
132 when absent; what the listed extensions add to the checkout step
133 from their answers to the ``checkout-inputs`` query. None of it is
134 the project's identity, which the project's answers hold alone.
135 """
136 from livery.workshop._entry import locked_uv_version
137 from livery.workshop._envfile import parse_env_file
138 from livery.workshop._queries import CHECKOUT_INPUTS, answer
140 contract = load_contract(root / "workshop.toml")
141 ci = contract.get("ci") or {}
142 runners = [str(runner) for runner in ci.get("runners") or ["ubuntu-latest"]]
143 narrowed = pull_request_runners(ci)
144 shards, pull_request_shards = _shard_facts(ci, runners, narrowed)
145 return {
146 "forge_kind": str((contract.get("forge") or {}).get("kind", "github")),
147 # What the listed extensions add to the checkout step, such as
148 # fetching the objects a git filter keeps outside the repository.
149 "checkout_inputs": dict(answer(root, CHECKOUT_INPUTS)),
150 "runners": runners,
151 "pull_request_runners": narrowed,
152 # The shards per runner label, one for a runner the tables do
153 # not name: every event's over every runner, and a pull
154 # request's over its runners.
155 "shards": shards,
156 "pull_request_shards": pull_request_shards,
157 "required_context": str(ci.get("required-context", "gate")),
158 "python_versions": python_matrix(root),
159 "gate_pythons": gate_pythons(root),
160 # The outer uv, the one tool that runs before the lock can
161 # speak: pinned to the lock's own uv, so the bootstrap is not
162 # the one unpinned link. Empty without a lock, and the
163 # bootstrap then stays unpinned rather than inventing a
164 # version.
165 "uv_pin": locked_uv_version(root),
166 # The system packages each job installs before it enters, the
167 # seam each deploying job publishes through, and the runner
168 # labels each runners job fans out to, by point and job: the
169 # declaration of a job knows why.
170 "installs": job_installs(root, everything),
171 "seams": job_seams(root, everything),
172 "job_runners": job_runners(root, everything),
173 # The committed .repo.env's keys: the offline, deterministic
174 # list of which secrets the entry step may carry into a job.
175 "env_keys": sorted(parse_env_file(root / ".repo.env")),
176 }
179def _secret_lines(answers: dict[str, Any]) -> list[str]:
180 """The entry step's environment lines: each declared key's secret, prefixed.
182 Each key the committed ``.repo.env`` declares may arrive as a CI
183 secret; the entry step carries it as ``RUNG_<KEY>``, and the
184 emission the entry runs writes the non-empty ones into a
185 runner-local file the cascade reads as the shared slot
186 (``WORKSHOP_SHARED_ENV_FILE``). Non-empty values only, so an
187 absent secret cannot mask a committed value, and a fork PR with
188 no secrets behaves like a machine without a shared file. Never
189 the whole secrets store: ``toJSON(secrets)`` would hand every job
190 and every third-party action the lot. Empty when the workspace
191 declares no keys.
192 """
193 from livery.workshop._envfile import RUNG_PREFIX
195 keys = [str(key) for key in answers.get("env_keys", [])]
196 return [f"{RUNG_PREFIX}{key}: ${{{{ secrets.{key} }}}}" for key in keys]
199def _setup_uv_step(answers: dict[str, Any]) -> str:
200 """The setup-uv step, uv pinned to the lock's own version, its cache off.
202 Nothing of uv's is cached: the only wheels the sync builds from
203 source are the workspace's own, rebuilt on every commit, and the
204 wheels it downloads arrive faster than an archive of them restores.
205 The cache is still placed on the runner's working drive by the
206 entry, so the sync links wheels into the venv instead of copying
207 across drives.
208 """
209 pin = str(answers.get("uv_pin", ""))
210 lines = [f" - uses: {ACTIONS['github']['setup-uv']}", " with:"]
211 if pin:
212 lines.append(f' version: "{pin}"')
213 lines.append(" enable-cache: false")
214 return "\n".join(lines) + "\n"
217def _store_cache_step() -> str:
218 """The tool store restored before the entry materialises it.
220 Keyed by the tools lock, the OS and the architecture, with the
221 prefix as the restore key, so a changed lock restores everything
222 unchanged and the store lands only the digests it lacks. A
223 restored folder is a tier the store verifies on access: an old or
224 torn archive costs a refetch, never a fault. `ci.run` sweeps the
225 store before the post-job save, so the archive carries the trees
226 the tools run from and not the artifacts they were extracted from.
227 """
228 return (
229 f" - uses: {ACTIONS['github']['cache']}\n"
230 " with:\n"
231 f" path: {STORE_HOME}\n"
232 " key: tools-${{ runner.os }}-${{ runner.arch }}"
233 "-${{ hashFiles('toolroom.lock') }}\n"
234 " restore-keys: tools-${{ runner.os }}-${{ runner.arch }}-\n"
235 )
238def _conan_cache_step() -> str:
239 """Conan's home restored around a job that builds native packages.
241 Keyed by the recipes, the OS and the architecture, with the
242 prefix as the restore key: a third-party package from Conan
243 Center is built from source once per key and downloaded from the
244 cache afterwards. The recipes are the key because they carry the
245 requirements; a range that resolves to a newer version inside an
246 unchanged recipe reuses the entry and builds that one package.
247 The cache is the speed extension and Conan Center the origin, so a
248 miss costs time, never a red leg.
249 """
250 # A forge's glob stops at a slash: a package in a group directory
251 # is one level deeper.
252 recipes = "packages/*/conanfile.py', 'packages/*/*/conanfile.py"
253 return (
254 f" - uses: {ACTIONS['github']['cache']}\n"
255 " with:\n"
256 f" path: {CONAN_HOME}\n"
257 " key: conan-${{ runner.os }}-${{ runner.arch }}"
258 f"-${{{{ hashFiles('{recipes}') }}}}\n"
259 " restore-keys: conan-${{ runner.os }}-${{ runner.arch }}-\n"
260 )
263def _installs(
264 answers: dict[str, Any],
265 point: Point,
266 job: Job,
267 joins: Sequence[tuple[Point, Job]] = (),
268) -> tuple[str, ...]:
269 """The system packages *job* of *point* installs before it enters, *joins* included."""
270 found = set(answers.get("installs", {}).get((point.name, job.name), ()))
271 for other, joined in joins:
272 found.update(answers.get("installs", {}).get((other.name, joined.name), ()))
273 return tuple(sorted(found))
276def _joins_of(
277 point: Point, job: Job, everything: tuple[Point, ...]
278) -> list[tuple[Point, Job]]:
279 """The joins of *job* of *point*: on the point itself and on the points inheriting it.
281 Each with the point it was contributed to, which conditions the
282 plumbing it adds: a join on the merge point of a job the gate
283 point declares renders on the gate point's job, on a push alone.
284 """
285 return [
286 (other, joined)
287 for other in everything
288 if other.name == point.name or other.inherits == point.name
289 for joined in other.jobs
290 if joined.joins and joined.name == job.name
291 ]
294def _condition(point: Point, other: Point) -> str:
295 """The event condition a step *other* adds to a job of *point* carries; none on its own point."""
296 return "" if other.name == point.name else _event_filter(other)
299def _if_line(condition: str) -> str:
300 return f" if: {condition}\n" if condition else ""
303def _artifact_root(everything: tuple[Point, ...], name: str) -> str:
304 """The directory a collected artifact *name* unpacks into: its publisher's paths' root."""
305 for point in everything:305 ↛ 309line 305 didn't jump to line 309 because the loop on line 305 didn't complete
306 for job in point.jobs:
307 if job.publishes == name and job.paths:
308 return job.paths[0].split("/", 1)[0]
309 return "."
312def _seam(answers: dict[str, Any], point: Point, job: Job) -> str:
313 """The seam *job* of *point* publishes through; ``""`` when it deploys nothing."""
314 return str(answers.get("seams", {}).get((point.name, job.name), ""))
317def _installs_step(packages: tuple[str, ...]) -> str:
318 """The step installing *packages* on a GitHub- or Gitea-shaped job; empty for none."""
319 if not packages:
320 return ""
321 return (
322 " - name: System packages\n"
323 " run: sudo apt-get update -q && sudo apt-get install"
324 f" -y -q {' '.join(packages)}\n"
325 )
328DRIVER_DIST = "livery-workshop"
329"""The distribution a re-dispatched wave may pin as its driver."""
332def _enter_step(answers: dict[str, Any], *, matrix_python: bool = False) -> str:
333 """The entry step: ``setup.sh github`` persists the emission.
335 Every step after it calls the runner and the venv tools bare,
336 from the persisted PATH. ``UV_PYTHON`` selects the matrix leg's
337 interpreter for the entry sync where a matrix exists, and the
338 declared keys' secrets ride the step's environment as
339 ``RUNG_<KEY>`` for the emission to materialise into the shared
340 slot.
341 """
342 lines: list[str] = []
343 if matrix_python:
344 lines.append("UV_PYTHON: ${{ matrix.python }}")
345 lines.extend(_secret_lines(answers))
346 env = " env:\n" + "".join(f" {line}\n" for line in lines)
347 return (
348 " - name: Enter the workspace\n"
349 + (env if lines else "")
350 + " run: bash setup.sh github\n"
351 )
354def _csv(values: list[Any], *, quoted: bool = False) -> str:
355 return ", ".join(f'"{v}"' if quoted else str(v) for v in values)
358def _labels(answers: dict[str, Any], point: Point, job: Job) -> list[str]:
359 """The runner labels *job* of *point* fans out to; empty when its function names none."""
360 found = answers.get("job_runners", {}).get((point.name, job.name), ())
361 return [str(label) for label in found]
364def _gitlab_image(answers: dict[str, Any], python: str) -> str:
365 """The pinned uv image for a GitLab job.
367 With a lock the tag carries the pin
368 (``<pin>-python<minor>-bookworm``), so the job's uv is the lock's
369 uv; without one the unversioned tag is the honest fallback.
370 """
371 pin = str(answers.get("uv_pin", ""))
372 prefix = f"{pin}-" if pin else ""
373 return f"ghcr.io/astral-sh/uv:{prefix}python{python}-bookworm"
376def _comment(text: str, indent: str = "") -> str:
377 """*text* as YAML comment lines under *indent*; empty for empty."""
378 import textwrap
380 if not text:
381 return ""
382 width = max(40, 72 - len(indent))
383 return "".join(f"{indent}# {line}\n" for line in textwrap.wrap(text, width=width))
386def _renders(point: Point, job: Job, answers: dict[str, Any]) -> bool:
387 """Whether *job* of *point* exists for this workspace.
389 A ``runners`` job exists when its function names a runner label
390 for this workspace; when it names none, the job does not render
391 and `_needs` drops a need on it. Every other job always exists.
392 """
393 return job.matrix != "runners" or bool(_labels(answers, point, job))
396def _points_of(workflow: str, everything: tuple[Point, ...]) -> tuple[Point, ...]:
397 """The points among *everything* whose shell *workflow* is, in order."""
398 return tuple(point for point in everything if point.workflow == workflow)
401def _needs(
402 point: Point, job: Job, answers: dict[str, Any], everything: tuple[Point, ...]
403) -> list[str]:
404 """The jobs *job* waits for that render for this workspace."""
405 owners = [other for other in everything if other.name == point.inherits]
406 rendered = {
407 other.name
408 for owner in (*owners, point)
409 for other in owner.jobs
410 if _renders(owner, other, answers)
411 }
412 return [need for need in job.needs if need in rendered]
415def _event_filter(point: Point) -> str:
416 """The Actions condition admitting *point*'s events alone."""
417 return " || ".join(f"github.event_name == '{event}'" for event in point.events)
420def _shard_facts(
421 ci: dict[str, Any], runners: Sequence[str], narrowed: Sequence[str]
422) -> tuple[dict[str, int], dict[str, int]]:
423 """The shards per runner label: every event's, and a pull request's.
425 Read as [livery.workshop.check_shards][] and
426 [livery.workshop.pull_request_shards][] read them, so the matrix
427 and the leg labels agree: ``[ci] shards`` over every runner, one
428 for a runner it does not name; ``[ci] pull-request-shards`` over
429 the pull request's runners, *narrowed*, or every event's counts for
430 those runners while that key is absent. A count outside the
431 contract refuses here, through `shard_counts`, before a line
432 renders.
433 """
434 shards = shard_counts(ci, key="shards", runners=runners, listed="[ci] runners")
435 if ci.get("pull-request-shards") is None:
436 return shards, {runner: shards[runner] for runner in narrowed}
437 pull = shard_counts(
438 ci,
439 key="pull-request-shards",
440 runners=narrowed,
441 listed=pull_request_listed(ci),
442 )
443 return shards, pull
446def _runners(answers: dict[str, Any]) -> tuple[list[str], list[str]]:
447 """Every event's runner labels, and a pull request's."""
448 runners = [str(runner) for runner in answers.get("runners", ["ubuntu-latest"])]
449 narrowed = [
450 str(runner) for runner in answers.get("pull_request_runners", runners[:1])
451 ]
452 return runners, narrowed
455def _shards(
456 answers: dict[str, Any], key: str, runners: Sequence[str]
457) -> dict[str, int]:
458 """The shards per runner the fact *key* holds, one for a runner it does not name."""
459 counts: Mapping[str, Any] = answers.get(key) or {}
460 return {runner: int(counts.get(runner, 1)) for runner in runners}
463def _split(counts: Mapping[str, int]) -> bool:
464 """Whether any runner in *counts* runs as more than one shard."""
465 return any(count > 1 for count in counts.values())
468def _carries_shards(answers: dict[str, Any]) -> bool:
469 """Whether the check matrix is ``include`` entries carrying shards.
471 It is when any runner runs as more than one shard on any event: the
472 entries of a split runner each name their shard, on the check job
473 or in both of the legs job's literals, and the one call passes
474 ``matrix.shard`` on every event, empty on a runner with one shard.
475 """
476 runners, narrowed = _runners(answers)
477 return _split(_shards(answers, "shards", runners)) or _split(
478 _shards(answers, "pull_request_shards", narrowed)
479 )
482def _narrows(answers: dict[str, Any]) -> bool:
483 """Whether a pull request's check legs differ from every other event's.
485 They do when the pull request runs on fewer runners, or when a
486 runner it runs on runs as another number of shards.
487 """
488 runners, narrowed = _runners(answers)
489 if narrowed != runners:
490 return True
491 shards = _shards(answers, "shards", runners)
492 pull = _shards(answers, "pull_request_shards", narrowed)
493 return pull != {runner: shards[runner] for runner in narrowed}
496def _entries(
497 runners: Sequence[str], pythons: Sequence[str], counts: Mapping[str, int]
498) -> list[tuple[str, str, str]]:
499 """One ``(os, python, shard)`` per matrix entry, in that order.
501 A runner with a count of one has one entry per Python with an empty
502 shard: the forge then names its job as the unsplit leg, ``check
503 (ubuntu-latest, 3.14)``, the name the runner gives it and keys its
504 rows by, and the call's shard reaches the runner empty, which it
505 reads as one shard of one.
506 """
507 entries: list[tuple[str, str, str]] = []
508 for runner in runners:
509 count = counts.get(runner, 1)
510 for python in pythons:
511 if count == 1:
512 entries.append((runner, python, ""))
513 continue
514 for index in range(1, count + 1):
515 entries.append((runner, python, str(Shard(index, count))))
516 return entries
519def _literal(
520 runners: Sequence[str],
521 pythons: Sequence[str],
522 counts: Mapping[str, int],
523 *,
524 sharded: bool,
525) -> str:
526 """One matrix as the JSON literal the legs job holds.
528 The ``include`` shape when *sharded*, each entry of a split runner
529 with its shard and an entry of a runner with one shard without the
530 key; the ``os`` and ``python`` lists otherwise.
531 """
532 matrix: dict[str, Any] = (
533 {
534 "include": [
535 {
536 "os": os_label,
537 "python": python,
538 **({"shard": shard} if shard else {}),
539 }
540 for os_label, python, shard in _entries(runners, pythons, counts)
541 ]
542 }
543 if sharded
544 else {"os": list(runners), "python": list(pythons)}
545 )
546 return json.dumps(matrix, separators=(",", ":"))
549def _legs_job(answers: dict[str, Any]) -> str:
550 """The job that picks the check legs' matrix by the event, as its output.
552 GitHub starts no run for a workflow whose matrix axis is an
553 expression, so the two literal matrices sit in this job's
554 environment, the event picks one, and the check job reads it with
555 ``fromJSON`` from the output: the one documented shape for a matrix
556 decided when the run starts. The decision is still the contract's;
557 the file carries two literals and which event takes which: a pull
558 request takes the narrowed one unless it carries
559 [livery.workshop.EVERY_RUNNER_LABEL][], and every other event takes
560 the full one. Both literals are ``include`` entries, each naming
561 its shard, when any runner runs as more than one shard on either
562 event, and the ``os`` and ``python`` lists otherwise. The job checks
563 nothing out and enters nothing, so it costs seconds.
564 """
565 from livery.workshop._points import EVERY_RUNNER_LABEL
567 runners, narrowed = _runners(answers)
568 pythons = [str(version) for version in answers.get("gate_pythons", ["3.11"])]
569 sharded = _carries_shards(answers)
570 full = _literal(
571 runners, pythons, _shards(answers, "shards", runners), sharded=sharded
572 )
573 pull = _literal(
574 narrowed,
575 pythons,
576 _shards(answers, "pull_request_shards", narrowed),
577 sharded=sharded,
578 )
579 narrowed_event = (
580 "github.event_name == 'pull_request' && !contains("
581 f"github.event.pull_request.labels.*.name, '{EVERY_RUNNER_LABEL}')"
582 )
583 return (
584 _comment(
585 "The check legs' matrix, two literals: a pull request's runners"
586 f" and every runner. A pull request without the {EVERY_RUNNER_LABEL}"
587 " label takes the first, every other run the second, and the"
588 " check job reads the pick from this job's output.",
589 " ",
590 )
591 + " legs:\n"
592 f" runs-on: {runners[0]}\n"
593 " outputs:\n"
594 " matrix: ${{ steps.legs.outputs.matrix }}\n"
595 " steps:\n"
596 " - id: legs\n"
597 " env:\n"
598 f" LEGS: ${{{{ {narrowed_event} && '{pull}' || '{full}' }}}}\n"
599 ' run: echo "matrix=$LEGS" >> "$GITHUB_OUTPUT"\n'
600 )
603def _call_step(prog: str, point: Point, job: Job, *, shard: bool = False) -> str:
604 """The one call: ``ci.run`` for the point and job, the matrix facts passed.
606 *shard* passes the entry's shard too, on a ``legs`` matrix whose
607 entries carry one.
608 """
609 call = f"{prog} ci.run --point={point.name} --job={job.name}"
610 if job.matrix in ("legs", "declared"):
611 passed = ' --shard="${{ matrix.shard }}"\n' if shard else ""
612 return (
613 " run: >-\n"
614 f" {call}\n"
615 ' --os="${{ matrix.os }}" --python="${{ matrix.python }}"\n'
616 + passed
617 )
618 if job.matrix == "pythons":
619 return (
620 f" run: >-\n {call}\n"
621 ' --python="${{ matrix.python }}"\n'
622 )
623 return f" run: {call}\n"
626def _call_env(job: Job, *, forge: str) -> str:
627 """What the call sees: the credential, the index token, the deploy key's ssh."""
628 lines: list[str] = []
629 if job.token == "job":
630 lines.append("FORGE_TOKEN: ${{ secrets.GITHUB_TOKEN }}")
631 elif job.token == "repository":
632 lines.append("FORGE_TOKEN: ${{ secrets.FORGE_TOKEN || secrets.GITHUB_TOKEN }}")
633 elif job.token == "secret":633 ↛ 634line 633 didn't jump to line 634 because the condition on line 633 was never true
634 lines.append("FORGE_TOKEN: ${{ secrets.FORGE_TOKEN }}")
635 elif job.token == "admin":
636 lines.append("FORGE_ADMIN_TOKEN: ${{ secrets.FORGE_ADMIN_TOKEN }}")
637 if job.publishes_index:
638 # A token publishes where the repository has one; on GitHub an
639 # absent secret arrives empty, which the publish verb drops
640 # before it spawns uv, so uv stays on trusted publishing.
641 secret = "PYPI_TOKEN" if forge == "github" else "UV_PUBLISH_TOKEN"
642 lines.append(f"UV_PUBLISH_TOKEN: ${{{{ secrets.{secret} }}}}")
643 if not lines:
644 return ""
645 return " env:\n" + "".join(f" {line}\n" for line in lines)
648#: The inputs the checkout step sets from the job's own declaration,
649#: which no answer to the ``checkout-inputs`` query may name.
650CHECKOUT_OWN = ("ref", "fetch-depth", "fetch-tags", "token")
653def checkout_inputs(answers: Mapping[str, Any], lookup: Lookup) -> dict[str, str]:
654 """Every input the answers add to the checkout step, each name to its value.
656 The rule of the ``checkout-inputs`` query, which the base's
657 contract file names. Each answer maps an input of the checkout
658 action to its value, written into the workflow as it stands.
660 Raises:
661 QueryError: when an answer names an input the step sets from the
662 job's declaration (``CHECKOUT_OWN``) or gives a value that is
663 not a string, naming the extension, or when two answers give
664 one input different values, naming both.
665 """
666 from livery.workshop._queries import QueryError, merged
668 for name, value in answers.items():
669 for key, held in cast("Mapping[str, object]", value).items():
670 if key in CHECKOUT_OWN:
671 raise QueryError(
672 f"{name} answers {key}, which the checkout step sets from"
673 " the job's declaration; answer another input"
674 )
675 if not isinstance(held, str):
676 raise QueryError(
677 f"{name} answers {key} with {held!r}, and an input's value"
678 " is a string, as the workflow writes it; quote it"
679 )
680 return dict(merged(answers, lookup))
683def _checkout_step(
684 point: Point, job: Job, *, forge: str, inputs: Mapping[str, str] | None = None
685) -> str:
686 """The checkout: as deep as the verbs need, at the dispatched ref, able to push.
688 *inputs* are what the listed extensions add to it, each written
689 before the inputs the job's declaration sets.
690 """
691 action = ACTIONS[forge]["checkout"]
692 with_lines = [
693 f" {name}: {value}" for name, value in (inputs or {}).items()
694 ]
695 if point.ref_input:
696 with_lines.append(f" ref: ${{{{ inputs.{point.ref_input} }}}}")
697 if job.fetch == "full":
698 with_lines.append(" fetch-depth: 0")
699 elif job.fetch == "tags":
700 with_lines.append(" fetch-tags: true")
701 elif job.fetch:
702 with_lines.append(f" fetch-depth: {job.fetch}")
703 if job.pushes:
704 # The push rides this checkout's credential: the job token may
705 # not push a ref whose commit carries a workflow file that
706 # differs from the tip's, and receipt tags are protected.
707 token = (
708 "${{ secrets.FORGE_TOKEN || github.token }}"
709 if forge == "github"
710 else "${{ secrets.FORGE_TOKEN }}"
711 )
712 with_lines.append(f" token: {token}")
713 lines = [f" - uses: {action}\n"]
714 if with_lines:
715 lines.append(" with:\n")
716 lines.extend(line + "\n" for line in with_lines)
717 return "".join(lines)
720def _collect_step(
721 job: Job, *, forge: str, everything: tuple[Point, ...], condition: str = ""
722) -> str:
723 """The artifact *job* collects, every leg's merged into its publisher's root.
725 *condition* is the event condition of the point that added the
726 collect to a job of another point, empty on the job's own. A
727 collect added that way never stops the job: the artifact is
728 missing when its publisher was red, and the job's own entries,
729 the verdict among them, still judge the run and say so.
730 """
731 if not job.collects:
732 return ""
733 action = ACTIONS[forge]["download"]
734 tolerant = " continue-on-error: true\n" if condition else ""
735 return (
736 f" - uses: {action}\n" + _if_line(condition) + tolerant + " with:\n"
737 f" pattern: {job.collects}*\n"
738 f" path: {_artifact_root(everything, job.collects)}\n"
739 " merge-multiple: true\n"
740 )
743def _publish_step(
744 job: Job, *, forge: str, matrix: bool = False, condition: str = ""
745) -> str:
746 """The artifact *job* publishes, its paths as declared, the leg's name on a *matrix*.
748 *condition* is the event condition of the point that added the
749 publish to a job of another point, empty on the job's own.
750 """
751 if not job.publishes:
752 return ""
753 action = ACTIONS[forge]["upload"]
754 name = job.publishes + ("-${{ matrix.os }}" if matrix else "")
755 return (
756 f" - uses: {action}\n" + _if_line(condition) + " with:\n"
757 f" name: {name}\n"
758 " path: |\n"
759 + "".join(f" {path}\n" for path in job.paths)
760 + " if-no-files-found: ignore\n"
761 )
764def _driver_step(prog: str, point: Point, *, forge: str) -> str:
765 """The driver pin, through its verb: the released workshop the input names.
767 Every job of a point that takes a ``workshop`` input pins it before
768 its one call, so one workshop drives the whole run; a job of any
769 other point pins nothing. The verb decides for itself on an empty
770 input, so the shell carries no condition.
771 """
772 if not any(item.name == "workshop" for item in point.inputs):
773 return ""
774 value = "${{ inputs.workshop }}" if forge != "gitlab" else "$workshop"
775 return (
776 " - name: Pin the driver\n"
777 f' run: {prog} release.driver --workshop="{value}"\n'
778 )
781_PAGES_GRANT = """ permissions:
782 contents: read
783 pages: write
784 id-token: write
785 environment:
786 name: github-pages
787 url: ${{ steps.deployment.outputs.page_url }}
788 concurrency:
789 group: pages
790 cancel-in-progress: false
791"""
793_PAGES_UPLOAD = f" - uses: {ACTIONS['github']['upload-pages']}\n"
795_PAGES_DEPLOY = f""" - id: deployment
796 uses: {ACTIONS["github"]["deploy-pages"]}
797"""
800def _pages_upload_step(condition: str = "") -> str:
801 """The upload of the built site as the pages artifact, under *condition*."""
802 return _PAGES_UPLOAD + _if_line(condition) + " with:\n path: site\n"
805def _pages_job(answers: dict[str, Any], point: Point, job: Job, other: Point) -> str:
806 """The forge's own pages deploy of the site *job* of *point* uploaded, for *other*.
808 No checkout and no entry: the one step deploys the artifact the
809 joined job uploaded, in the pages environment, on *other*'s events.
810 """
811 first = str(next(iter(answers.get("runners", ["ubuntu-latest"]))))
812 condition = _condition(point, other)
813 return (
814 _comment(
815 f"The forge's pages deploy of the site the {job.name} job uploaded:"
816 " no checkout and no entry, the pages environment alone.",
817 " ",
818 )
819 + " pages:\n"
820 + (f" if: {condition}\n" if condition else "")
821 + f" needs: [{job.name}]\n"
822 + _PAGES_GRANT
823 + f" runs-on: {first}\n steps:\n"
824 + _PAGES_DEPLOY
825 )
828def _grants(job: Job, *, pages: bool) -> str:
829 """GitHub's grants for *job*: organisation defaults are read-only."""
830 if pages:830 ↛ 831line 830 didn't jump to line 831 because the condition on line 830 was never true
831 return _PAGES_GRANT
832 lines: list[str] = []
833 if job.environment:
834 # Trusted publishing: the id token is minted for the named
835 # environment.
836 lines.append(" id-token: write")
837 if job.writes:
838 lines.append(" contents: write")
839 if job.dispatches:
840 # Starting a workflow through the API: the workflow token
841 # answers 403 ("Resource not accessible by integration")
842 # without it, and the wave never starts.
843 lines.append(" actions: write")
844 if not lines:
845 return ""
846 return " permissions:\n" + "".join(line + "\n" for line in lines)
849def _actions_job(
850 answers: dict[str, Any],
851 prog: str,
852 point: Point,
853 job: Job,
854 *,
855 forge: str,
856 everything: tuple[Point, ...],
857) -> str:
858 """One job of *point* for GitHub or Gitea, from its declaration.
860 A job of a point that shares its file with a point nobody
861 inherits from runs on its own point's events alone; the gate's
862 jobs carry no filter, since the merge point inherits them.
863 """
864 runners = [str(runner) for runner in answers.get("runners", ["ubuntu-latest"])]
865 first = runners[0]
866 pages = forge == "github" and _seam(answers, point, job) == "pages"
867 joins = _joins_of(point, job, everything)
868 lines = [_comment(job.note, " "), f" {job.name}:\n"]
869 conditions = []
870 if job.always:
871 conditions.append("always()")
872 shared = [
873 other
874 for other in _points_of(point.workflow, everything)
875 if other.name != point.name
876 ]
877 if shared and not any(other.inherits == point.name for other in shared):
878 conditions.append(_event_filter(point))
879 if conditions:
880 lines.append(f" if: {' && '.join(conditions)}\n")
881 needs = _needs(point, job, answers, everything)
882 if job.matrix == "legs" and _narrows(answers):
883 needs = ["legs", *needs]
884 if needs:
885 lines.append(f" needs: [{', '.join(needs)}]\n")
886 if forge == "github":
887 lines.append(_grants(job, pages=pages))
888 if job.environment:
889 lines.append(f" environment: {job.environment}\n")
890 if job.matrix == "legs":
891 gate = [str(version) for version in answers.get("gate_pythons", ["3.11"])]
892 if _narrows(answers):
893 lines.append(
894 " strategy:\n fail-fast: false\n"
895 " matrix: ${{ fromJSON(needs.legs.outputs.matrix) }}\n"
896 " runs-on: ${{ matrix.os }}\n"
897 )
898 elif _carries_shards(answers):
899 # One entry per os, python and shard: the forge names each
900 # job by the entry's values in order, ``check (windows-latest,
901 # 3.14, 2of4)``, so the job carries no name of its own, and
902 # a runner with one shard has no shard key, so its job is
903 # named as the unsplit leg the runner keys its rows by.
904 lines.append(" strategy:\n fail-fast: false\n matrix:\n")
905 lines.append(" include:\n")
906 counts = _shards(answers, "shards", runners)
907 for os_label, python, shard in _entries(runners, gate, counts):
908 tail = f", shard: {shard}" if shard else ""
909 lines.append(
910 f' - {{os: {os_label}, python: "{python}"{tail}}}\n'
911 )
912 lines.append(" runs-on: ${{ matrix.os }}\n")
913 else:
914 lines.append(
915 " strategy:\n fail-fast: false\n matrix:\n"
916 f" os: [{_csv(runners)}]\n"
917 f" python: [{_csv(gate, quoted=True)}]\n"
918 " runs-on: ${{ matrix.os }}\n"
919 )
920 elif job.matrix == "pythons":
921 pythons = _csv(list(answers.get("python_versions", ["3.11"])), quoted=True)
922 lines.append(
923 " strategy:\n fail-fast: false\n matrix:\n"
924 f" python: [{pythons}]\n runs-on: {first}\n"
925 )
926 elif job.matrix == "runners":
927 lines.append(
928 " strategy:\n fail-fast: false\n matrix:\n"
929 f" os: [{_csv(_labels(answers, point, job))}]\n"
930 " runs-on: ${{ matrix.os }}\n"
931 )
932 elif job.matrix == "declared":
933 lines.append(
934 " strategy:\n fail-fast: false\n matrix:\n"
935 f" os: [{_csv(list(job.runners))}]\n"
936 f" python: [{_csv(list(job.pythons), quoted=True)}]\n"
937 " runs-on: ${{ matrix.os }}\n"
938 )
939 else:
940 lines.append(f" runs-on: {first}\n")
941 lines.append(" steps:\n")
942 lines.append(
943 _checkout_step(point, job, forge=forge, inputs=answers.get("checkout_inputs"))
944 )
945 if forge == "github":
946 lines.append(_setup_uv_step(answers))
947 lines.append(_collect_step(job, forge=forge, everything=everything))
948 for other, joined in joins:
949 lines.append(
950 _collect_step(
951 joined,
952 forge=forge,
953 everything=everything,
954 condition=_condition(point, other),
955 )
956 )
957 lines.append(_installs_step(_installs(answers, point, job, joins)))
958 if forge == "github":
959 lines.append(_store_cache_step())
960 if job.conan_cache:
961 lines.append(_conan_cache_step())
962 lines.append(
963 _enter_step(
964 answers, matrix_python=job.matrix in ("legs", "pythons", "declared")
965 )
966 )
967 lines.append(_driver_step(prog, point, forge=forge))
968 lines.append(f" - name: {job.step or job.name.capitalize()}\n")
969 lines.append(_call_env(job, forge=forge))
970 lines.append(
971 _call_step(
972 prog,
973 point,
974 job,
975 shard=job.matrix == "legs" and _carries_shards(answers),
976 )
977 )
978 lines.append(_publish_step(job, forge=forge, matrix=bool(job.matrix)))
979 for other, joined in joins:
980 condition = _condition(point, other)
981 lines.append(
982 _publish_step(
983 joined, forge=forge, matrix=bool(job.matrix), condition=condition
984 )
985 )
986 if forge == "github" and _seam(answers, other, joined) == "pages":
987 lines.append(_pages_upload_step(condition))
988 if pages:988 ↛ 989line 988 didn't jump to line 989 because the condition on line 988 was never true
989 lines.append(_pages_upload_step() + _PAGES_DEPLOY)
990 return "".join(lines)
993def _actions_workflow(
994 answers: dict[str, Any],
995 prog: str,
996 workflow: str,
997 *,
998 forge: str,
999 everything: tuple[Point, ...] | None = None,
1000) -> str:
1001 """The workflow file *workflow* for GitHub or Gitea, from the points that share it.
1003 *everything* is the workspace's points, the builtin four when
1004 absent.
1005 """
1006 everything = everything if everything is not None else points(None)
1007 owners_all = _points_of(workflow, everything)
1008 lines = [f"name: {workflow.removesuffix('.yml')}\n\n"]
1009 for point in owners_all:
1010 lines.append(_comment(point.note))
1011 lines.append("on:\n")
1012 for event in EVENT_NAMES:
1013 owners = [point for point in owners_all if event in point.events]
1014 if not owners:
1015 continue
1016 if event == "pull_request":
1017 # The default types plus labeled: a label a verb or a person
1018 # sets starts a run, whose legs job reads it.
1019 lines.append(
1020 " pull_request:\n types: [opened, synchronize, reopened, labeled]\n"
1021 )
1022 elif event == "push":
1023 lines.append(" push:\n branches: [main]\n")
1024 elif event == "schedule":
1025 lines.append(f' schedule:\n - cron: "{owners[0].cron}"\n')
1026 else:
1027 inputs = owners[0].inputs
1028 if not inputs:
1029 lines.append(" workflow_dispatch:\n")
1030 continue
1031 lines.append(" workflow_dispatch:\n inputs:\n")
1032 for item in inputs:
1033 lines.append(f" {item.name}:\n")
1034 lines.append(f" description: {item.description}\n")
1035 lines.append(
1036 f" required: {'true' if item.required else 'false'}\n"
1037 )
1038 if not item.required:
1039 lines.append(f' default: "{item.default}"\n')
1040 lines.append("\njobs:\n")
1041 for point in owners_all:
1042 for job in point.jobs:
1043 if job.joins:
1044 continue
1045 if job.matrix == "legs" and _narrows(answers):
1046 lines.append(_legs_job(answers))
1047 if _renders(point, job, answers):
1048 lines.append(
1049 _actions_job(
1050 answers, prog, point, job, forge=forge, everything=everything
1051 )
1052 )
1053 if forge == "github":
1054 for point in owners_all:
1055 for job in point.jobs:
1056 for other, joined in _joins_of(point, job, everything):
1057 if not job.joins and _seam(answers, other, joined) == "pages":
1058 lines.append(_pages_job(answers, point, job, other))
1059 return "".join(lines)
1062def _gitlab_rules(point: Point, everything: tuple[Point, ...]) -> str:
1063 """The rules admitting *point*'s runs, and those of the points inheriting it."""
1064 events: list[str] = list(point.events)
1065 for other in everything:
1066 if other.inherits == point.name:
1067 events.extend(event for event in other.events if event not in events)
1068 lines = [" rules:\n", " - if: $CI_COMMIT_TAG\n when: never\n"]
1069 for event in events:
1070 if event == "pull_request":
1071 condition = '$CI_PIPELINE_SOURCE == "merge_request_event"'
1072 elif event == "push":
1073 condition = '$CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"'
1074 elif event == "schedule":
1075 condition = (
1076 '$CI_PIPELINE_SOURCE == "schedule"'
1077 f' && $FORGE_WORKFLOW == "{point.workflow}"'
1078 )
1079 else:
1080 condition = f'$FORGE_WORKFLOW == "{point.workflow}"'
1081 lines.append(f" - if: '{condition}'\n")
1082 return "".join(lines)
1085def _gitlab_job(
1086 answers: dict[str, Any],
1087 prog: str,
1088 point: Point,
1089 job: Job,
1090 *,
1091 image: str,
1092 everything: tuple[Point, ...],
1093) -> str:
1094 """One job of *point* in the GitLab document, from its declaration.
1096 One executor, one image: a ``legs`` matrix is one leg on the first
1097 runner's label and the first gate Python, so its rows key the same
1098 leg the union expects, and it runs as the shards ``[ci] shards``
1099 gives the first runner through ``parallel: matrix``, each passing
1100 its ``SHARD``; the one document serves every event, so a pull
1101 request's counts are not read. A ``pythons`` or ``runners`` matrix
1102 is one job. A job deploying through the ``pages`` seam is GitLab
1103 Pages' own: a job named ``pages`` publishing ``public/``. A job
1104 that pushes, or writes the store, rewrites origin with the push
1105 token first, since the job token cannot push.
1106 """
1107 joins = _joins_of(point, job, everything)
1108 packages = " ".join(_installs(answers, point, job, joins))
1109 first = str(next(iter(answers.get("runners", ["ubuntu-latest"]))))
1110 stage = "release" if point.name in ("merge", "release") else "check"
1111 pages = _seam(answers, point, job) == "pages"
1112 name = "pages" if pages else job.name
1113 lines = [
1114 _comment(job.note),
1115 f"{name}:\n",
1116 f" stage: {stage}\n",
1117 f" image: {image}\n",
1118 ]
1119 count = _shards(answers, "shards", [first])[first] if job.matrix == "legs" else 1
1120 if count > 1:
1121 spelled = ", ".join(f'"{Shard(index, count)}"' for index in range(1, count + 1))
1122 lines.append(f" parallel:\n matrix:\n - SHARD: [{spelled}]\n")
1123 needs = _needs(point, job, answers, everything)
1124 if needs:
1125 lines.append(f" needs: [{', '.join(needs)}]\n")
1126 variables: list[str] = []
1127 if job.fetch in ("full", "tags"):
1128 variables.append(' GIT_DEPTH: "0"')
1129 elif job.fetch:
1130 variables.append(f' GIT_DEPTH: "{job.fetch}"')
1131 if job.token == "admin":
1132 variables.append(" FORGE_ADMIN_TOKEN: $FORGE_ADMIN_TOKEN")
1133 if variables:
1134 lines.append(" variables:\n" + "".join(v + "\n" for v in variables))
1135 rules = _gitlab_rules(point, everything)
1136 if job.always:
1137 rules = rules.replace(" - if: '", " - when: always\n if: '")
1138 lines.append(rules)
1139 lines.append(" script:\n")
1140 if point.ref_input:
1141 # The pipeline runs on the base branch; the dispatch names the
1142 # commit to publish in a variable, and the wave reads it there.
1143 lines.append(f' - git checkout --quiet "${point.ref_input}"\n')
1144 if job.pushes:
1145 lines.append(" - git fetch --tags\n")
1146 if job.pushes or job.writes:
1147 # The job token cannot push: a store write and a receipt tag
1148 # ride the push token. The address
1149 # is the server's own protocol, host and port: an instance
1150 # off 443 (the local one) is unreachable at a bare https host.
1151 lines.append(
1152 ' - git remote set-url origin "${CI_SERVER_PROTOCOL}://oauth2:'
1153 "${GITLAB_PUSH_TOKEN}@${CI_SERVER_HOST}:${CI_SERVER_PORT}/"
1154 '${CI_PROJECT_PATH}.git"\n'
1155 )
1156 if packages:
1157 # Root in the container image: no sudo.
1158 lines.append(f" - apt-get update -q && apt-get install -y -q {packages}\n")
1159 lines.append(" - source setup.sh gitlab\n")
1160 driver = _driver_step(prog, point, forge="gitlab")
1161 if driver:
1162 lines.append(f" - {driver.split('run: ', 1)[1]}")
1163 call = f"{prog} ci.run --point={point.name} --job={job.name}"
1164 if job.matrix == "legs":
1165 python = str(next(iter(answers.get("gate_pythons", ["3.11"]))))
1166 call += f' --os="{first}" --python="{python}"'
1167 if count > 1:
1168 call += ' --shard="$SHARD"'
1169 elif job.matrix == "declared":
1170 call += f' --os="{job.runners[0]}" --python="{job.pythons[0]}"'
1171 elif job.matrix == "pythons":
1172 python = str(next(iter(answers.get("python_versions", ["3.11"]))))
1173 call += f' --python="{python}"'
1174 lines.append(f" - {call}\n")
1175 if pages:1175 ↛ 1176line 1175 didn't jump to line 1176 because the condition on line 1175 was never true
1176 lines.append(" - mv site public\n artifacts:\n paths: [public]\n")
1177 return "".join(lines) + "\n"
1178 # The job's own artifact, then what the joins publish and the site
1179 # a joined pages seam hands to the pages job; a join's artifact
1180 # expires, since the deploy that reads it follows at once.
1181 kept = list(job.paths) if job.publishes else []
1182 joined_paths: list[str] = []
1183 for other, joined in joins:
1184 joined_paths += list(joined.paths) if joined.publishes else []
1185 if _seam(answers, other, joined) == "pages":
1186 joined_paths.append("site")
1187 paths = kept + [path for path in joined_paths if path not in kept]
1188 if paths:
1189 spelled = ", ".join(f'"{path}"' for path in paths)
1190 lines.append(f" artifacts:\n paths: [{spelled}]\n")
1191 if joined_paths:
1192 lines.append(" expire_in: 1 day\n")
1193 return "".join(lines) + "\n"
1196def _gitlab_document(
1197 answers: dict[str, Any], prog: str, *, everything: tuple[Point, ...] | None = None
1198) -> str:
1199 """The one GitLab document: every point's jobs, the builtin four by default.
1201 The merge point's dispatch job starts the wave through the API at
1202 the base branch with the squash in the ``ref`` variable, which the
1203 document routes on ``FORGE_WORKFLOW`` like a hand dispatch.
1204 """
1205 python = str(next(iter(answers.get("python_versions", ["3.11"]))))
1206 image = _gitlab_image(answers, python)
1207 lines = [
1208 """# The gate, the merge point, the nightly and the train, GitLab-shaped,
1209# generated by the workshop. One pipeline definition: workflow rules
1210# admit FORGE_WORKFLOW-routed pipelines (a dispatch, the clock), merge
1211# requests and main, and every pipeline is named after its workflow
1212# file, so a run reads on every forge the same way and a dispatched
1213# gate is told from a dispatched wave. Every job sources the entry
1214# script in its own shell, then calls the runner bare. The clock
1215# itself is a pipeline schedule, a project setting the governance
1216# reconcile creates, never a line here. GitLab CI variables arrive as
1217# process environment, the cascade's highest rung already: declare
1218# PYTHON_PUBLISH_INDEX, PYTHON_REGISTRY_URL, FORGE_TOKEN,
1219# UV_PUBLISH_TOKEN and GITLAB_PUSH_TOKEN (a project access token with
1220# write_repository: the job token cannot push, and the state store
1221# and the receipt tags are pushes) as CI
1222# variables, masked where their values allow it.
1223workflow:
1224 name: $FORGE_WORKFLOW
1225 rules:
1226 - if: $FORGE_WORKFLOW
1227 - if: $CI_PIPELINE_SOURCE == "merge_request_event"
1228 variables:
1229 FORGE_WORKFLOW: ci.yml
1230 - if: $CI_COMMIT_BRANCH == "main"
1231 variables:
1232 FORGE_WORKFLOW: ci.yml
1234stages: [check, release]
1236"""
1237 ]
1238 everything = everything if everything is not None else points(None)
1239 for point in everything:
1240 for job in point.jobs:
1241 if job.joins or not _renders(point, job, answers):
1242 continue
1243 lines.append(
1244 _gitlab_job(
1245 answers, prog, point, job, image=image, everything=everything
1246 )
1247 )
1248 for other, joined in _joins_of(point, job, everything):
1249 if _seam(answers, other, joined) == "pages":
1250 lines.append(
1251 _gitlab_pages_job(
1252 job, other, image=image, everything=everything
1253 )
1254 )
1255 return "".join(lines)
1258def _gitlab_pages_job(
1259 job: Job, other: Point, *, image: str, everything: tuple[Point, ...]
1260) -> str:
1261 """GitLab Pages' own job, publishing the site *job* kept, on *other*'s events."""
1262 return (
1263 _comment(
1264 f"GitLab Pages' deploy of the site the {job.name} job kept: no"
1265 " entry, the artifact moved to public/."
1266 )
1267 + f"pages:\n stage: release\n image: {image}\n needs: [{job.name}]\n"
1268 + _gitlab_rules(other, everything)
1269 + " script:\n - mv site public\n artifacts:\n paths: [public]\n\n"
1270 )
1273def generate(root: Path) -> dict[str, str]:
1274 """Every generated CI file for *root*'s forge kind, by path.
1276 The workflows call the CLI by the name this process runs under,
1277 so a branded runner emits workflows that call itself and needs
1278 no configuration. The emitted ``setup.sh`` at the root is the
1279 entry every workflow's jobs share. The template-artifact job is
1280 emitted only for a home: the contract declares where to publish
1281 and a member extension ships the tree; an ordinary instance's
1282 release has no templates to publish.
1283 """
1284 from livery.workshop._entry import entry_script
1285 from livery.workshop._provenance import generated_header
1287 prog = footman.prog()
1288 everything = emitted_points(root)
1289 facts = _facts(root, everything)
1290 kind = str(facts["forge_kind"])
1291 header = generated_header("#")
1292 if kind in ("github", "gitea"):
1293 # One file per workflow: the gate and the merge point share
1294 # ci.yml, the nightly, the release and every contributed point
1295 # have their own.
1296 workflows = sorted({point.workflow for point in everything})
1297 files = {
1298 f".{kind}/workflows/{workflow}": _actions_workflow(
1299 facts, prog, workflow, forge=kind, everything=everything
1300 )
1301 for workflow in workflows
1302 }
1303 else:
1304 files = {".gitlab-ci.yml": _gitlab_document(facts, prog, everything=everything)}
1305 files["setup.sh"] = entry_script(root)
1306 return {path: header + content for path, content in files.items()}
1309def generated_files(root: Path) -> dict[Path, str]:
1310 """The generated artifacts as absolute paths under *root*."""
1311 return {root / relative: content for relative, content in generate(root).items()}
1314#: What every generated file opens with, whatever runner wrote it.
1315GENERATED_MARK = "# Generated by the workshop from workshop.toml"
1318def retired_files(root: Path) -> tuple[Path, ...]:
1319 """The generated workflow files under *root* this emission does not own, to delete.
1321 Every file in the forge's workflow directory that opens with
1322 `GENERATED_MARK` and is not in this emission is retired: the
1323 workflow of a point a package contributed and that went with the
1324 package. A file without the mark is a person's and is never
1325 touched.
1326 """
1327 found: list[Path] = []
1328 owned = set(generate(root))
1329 for directory in (".github/workflows", ".gitea/workflows"):
1330 folder = root / directory
1331 if not folder.is_dir():
1332 continue
1333 for path in sorted(folder.glob("*.yml")):
1334 relative = path.relative_to(root).as_posix()
1335 if relative in owned:
1336 continue
1337 try:
1338 head = path.read_text("utf-8", errors="replace")[: len(GENERATED_MARK)]
1339 except OSError:
1340 continue
1341 if head == GENERATED_MARK:
1342 found.append(path)
1343 return tuple(found)