livery.workshop._ci_context¶
livery.workshop._ci_context ¶
The CI run this process belongs to, and the state store built with its policy.
The run context reads the runner's environment: GitHub's and Gitea's
GITHUB_* variables, GitLab's CI_*. livery.workshop.state_store
builds the livery.git.StateStore every verb reads and writes the
workshop's series through, with the three answers the store takes as
construction data: whether this is a CI run, the identity every commit
carries, and the variable a published listing travels in.
Classes:
| Name | Description |
|---|---|
RunContext |
The CI run this process belongs to, as the runner's environment names it. |
Functions:
| Name | Description |
|---|---|
state_store |
Open the state store of the checkout at root, with the workshop's policy. |
event_payload |
The runner's event payload, or |
dispatch_inputs |
The dispatch inputs names, as the run received them; |
run_context |
The CI run this process runs in, or |
ci_run |
The CI run this process belongs to, or None at a desk. |
Attributes:
| Name | Type | Description |
|---|---|---|
LEG_VARIABLE |
|
|
POINT_VARIABLE |
|
|
SNAPSHOT_VARIABLE |
|
|
GITLAB_EVENTS |
|
GITLAB_EVENTS
module-attribute
¶
GITLAB_EVENTS = {'merge_request_event': 'pull_request', 'api': 'workflow_dispatch', 'trigger': 'workflow_dispatch', 'web': 'workflow_dispatch'}
RunContext
dataclass
¶
RunContext(forge: str, run_id: str, event: str, ref: str, head_sha: str = '', base_ref: str = '', leg: str = '', head_ref: str = '', labels: tuple[str, ...] = (), attempt: str = '')
The CI run this process belongs to, as the runner's environment names it.
Attributes:
| Name | Type | Description |
|---|---|---|
forge |
str
|
|
run_id |
str
|
The forge's identifier of the run (GitLab: the pipeline). |
event |
str
|
What started the run ( |
ref |
str
|
The ref the run is for, as the runner spells it. |
head_sha |
str
|
The commit the forge files the run under. On a pull request the checkout is the merge commit the forge synthesised, and the run's own head is the pull request's head, which the event payload names; on a push both are the same commit. Empty when the runner did not say. |
base_ref |
str
|
The branch a pull request proposes into, as the event payload names it (GitLab: the merge request's target); empty on a push or when the runner did not say. |
leg |
str
|
The check leg this process runs in ( |
head_ref |
str
|
The branch a pull request comes from, as the event payload names it (GitLab: the merge request's source), the base of the branch's own coverage record; empty on a push or when the runner did not say. |
labels |
tuple[str, ...]
|
The pull request's label names, as the event payload
names them (GitLab: |
attempt |
str
|
Which attempt of the run this is, as the runner
counts them from 1 (GitHub's and Gitea's
|
shard
property
¶
shard: Shard
The shard the leg runs as, read from the end of leg; one of one without.
check-windows-latest-3.14-2of4 runs as the second of four
shards; check-ubuntu-latest-3.14, and an empty leg, as the
one shard of one. The label is the only source, so the shard
and the leg cannot disagree. A livery.workshop.Shard.
Raises:
| Type | Description |
|---|---|
ValueError
|
When the label ends in a shard spelling outside
the form, such as |
state_store ¶
state_store(root: Path) -> StateStore
Open the state store of the checkout at root, with the workshop's policy.
A CI run may write a ci_only series and a desk may not; every
commit the store makes is by the tools' identity
(livery.git.tool_identity); a published listing travels in the
WORKSHOP_SNAPSHOT variable. Every series the workshop and its
extensions keep is read and written through it.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
event_payload ¶
The runner's event payload, or None when there is none to read.
GitHub and Gitea write the event that started the run to the file
GITHUB_EVENT_PATH names; a payload that is missing or does not
parse reads as none, so a caller falls back rather than fails.
GitLab writes no file and carries the same facts as variables, so a
merge request pipeline answers with the payload's pull_request
shape built from CI_MERGE_REQUEST_*: the iid as the number, the
title, the source branch and head sha, and the target branch. Any
other GitLab pipeline has no payload.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
dispatch_inputs ¶
The dispatch inputs names, as the run received them; "" for one it did not.
GitHub and Gitea carry a dispatch's inputs in the event payload
under inputs; GitLab carries them as pipeline variables, which
arrive as environment variables named by the input. A run that no
dispatch started, or a process outside CI, has none, and every
name reads empty.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
run_context ¶
run_context(environ: dict[str, str] | None = None) -> RunContext | None
The CI run this process runs in, or None outside CI.
GitHub and Gitea both speak the GITHUB_* variables (the
act_runner keeps GitHub's names and adds GITEA_ACTIONS);
GitLab speaks GITLAB_CI and CI_*, and its pipeline source
is read through GITLAB_EVENTS, so a merge request pipeline
narrows, records and checks titles the way a pull request run does.
Source code in packages/workshop/src/livery/workshop/_ci_context.py
ci_run ¶
ci_run(environ: dict[str, str] | None = None) -> RunContext | None
The CI run this process belongs to, or None at a desk.
Read from the runner's environment, environ when given, the
process's own otherwise: GitHub's and Gitea's GITHUB_*
variables, GitLab's CI_*. An extension that behaves
differently in CI asks this, never a variable of one forge.