livery.workshop._workflow_tasks¶
livery.workshop._workflow_tasks ¶
The workflow group: the reserved-branch lifecycles' surface.
workflow.abort stops a reserved workflow, policy layered over the
same teardown mechanism fm abandon uses. The hidden
workflow.configure asserts repository settings from the workspace
contract, run at birth, as release aftercare, and after an abort.
The lifecycle drivers (workflow.release, workflow.update)
arrive with their own modules; this one owns what every kind shares.
Functions:
| Name | Description |
|---|---|
render_workflows |
Print one line per workflow: name, state, author, the way forward. |
abort_policy |
The abort's state gates, then the shared teardown. |
workflow_abort |
Stop a reserved workflow: disarm, close its PR, tear its branch down. |
required_context_string |
The status context string protection must require, per forge. |
contract_config |
The repository settings the workspace contract states. |
contract_changed |
The governed paths HEAD's own commit changed; empty is none. |
workflow_configure |
Assert the contract's repository settings; idempotent drift repair. |
assert_configuration |
The configure flow, root-taking so birth can call it too. |
reconcile_schedules |
Make the forge's clock match the points that run on it; what was done. |
Attributes:
| Name | Type | Description |
|---|---|---|
workflow |
|
|
GOVERNED_PATHS |
|
|
SCHEDULE_PREFIX |
|
GOVERNED_PATHS
module-attribute
¶
render_workflows ¶
render_workflows(states: tuple[WorkflowStatus, ...]) -> None
Print one line per workflow: name, state, author, the way forward.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
abort_policy ¶
abort_policy(repo: Repository, root: Path, states: tuple[WorkflowStatus, ...], name: str, *, force: bool, base: str = 'main', interactive: bool = False) -> None
The abort's state gates, then the shared teardown.
Bare with one workflow targets it; several ask interactively or
refuse by name, silence never picks a teardown target. UNKNOWN
refuses without force, never tear down on a blip; a live state
refuses without force; a bare --force with several in flight
refuses, force one by name.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
workflow_abort ¶
workflow_abort(name: Annotated[str, suggest(_active_names, strict=False), doc('the workflow to stop; bare targets the only one in flight')] = '', force: Annotated[bool, doc('tear down a live or unreadable workflow')] = False) -> None
Stop a reserved workflow: disarm, close its PR, tear its branch down.
Bare targets the only workflow in flight; with several, an
interactive run lists them and asks, a non-interactive run
refuses naming each. A live or unreadable workflow refuses
without --force, and a bare --force never sweeps several.
Ends by re-asserting the repository configuration, so an aborted
workflow that had moved settings forward cannot leave protection
demanding contexts that never report again.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
required_context_string ¶
The status context string protection must require, per forge.
The name in the contract is the gate job's; forges report it
differently. GitHub reports the job name itself. Gitea reports
Actions statuses as <workflow name> / <job> (<event>), so a
bare job name never matches and the required check can never
pass; the workflow's emitted name is ci, and the merge-
deciding event is the pull request's. GitLab has no required
contexts (the capability probe drops the half), so its spelling
never reaches a forge.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
contract_config ¶
contract_config(root: Path) -> RepoConfig
The repository settings the workspace contract states.
The approvals half derives from the owner declarations (livery.workshop._governance): the highest declared count, with codeowner review required whenever anyone is declared. A forge without the min_approvals capability gets the config without that half rather than a refusal: governance degrades to the codeowners file alone, which is what the forge can honour.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
contract_changed ¶
The governed paths HEAD's own commit changed; empty is none.
The merge point's commit is one squash on main, so its file list is the merge's whole diff. A shallow checkout of depth one reads a squash as a root commit and lists every file, so the shell fetches two.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
workflow_configure ¶
workflow_configure(if_changed: Annotated[bool, doc('only when HEAD changed a contract or the owners file')] = False) -> None
Assert the contract's repository settings; idempotent drift repair.
Run at repository birth, as release aftercare, after an abort,
and at the merge point, where --if-changed makes it classify
its own commit and exit fast when no contract path changed.
Resolves the admin ladder (FORGE_ADMIN_TOKEN, host-qualified
first, the everyday token as the fallback); a refused write
teaches the grant and the variable. Declared owners the forge
does not know refuse before anything is applied: a review chain
pointing at nobody is worse than unapplied settings.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
assert_configuration ¶
assert_configuration(root: Path) -> None
The configure flow, root-taking so birth can call it too.
Source code in packages/workshop/src/livery/workshop/_workflow_tasks.py
reconcile_schedules ¶
reconcile_schedules(repo: Repository, forge: Forge) -> list[str]
Make the forge's clock match the points that run on it; what was done.
A forge whose clock is in the workflow file (GitHub, Gitea) has
nothing to reconcile and says so. On a forge with pipeline
schedules (GitLab) every declared point whose events include
schedule gets one schedule on main, named
workshop: <point>, at the point's cron, starting its pipeline
with FORGE_WORKFLOW set to the point's workflow file so the
document routes it; a schedule the reconcile named for a point
no longer declared is deleted.