livery.forge._merge_state¶
livery.forge._merge_state ¶
Classify a merge refusal into one state, whatever the forge said.
Every forge holds a merge for its own reasons in its own words:
GitLab publishes an enum (detailed_merge_status), GitHub
publishes another (mergeable_state), and Gitea answers 405 with
prose. This module maps all three onto one vocabulary, so a caller
decides by category, never by forge dialect:
in-progress: the forge has not decided yet; following through resolves it.recoverable: someone can act, and re-running afterwards merges; the message says what would recover it.terminal: the instruction is void (the pull request is closed without merging).success: it is merged, including discovered merged.
A forge answer outside the map raises livery.forge.ForgeError naming the native words: the map is updated in software, never guessed at runtime, and an unmapped state must not hang a wait.
Classes:
| Name | Description |
|---|---|
MergeState |
One classified merge hold. |
Functions:
| Name | Description |
|---|---|
merge_state |
The vocabulary member state, carrying native verbatim. |
classify_gitlab_detailed_status |
GitLab's |
classify_github_mergeable_state |
GitHub's |
classify_gitea_merge_refusal |
Gitea's 405 prose as a merge state; the inputs disambiguate. |
classify_merge_refusal |
Classify a merge-endpoint refusal by the forge kind. |
Attributes:
| Name | Type | Description |
|---|---|---|
MergeCategory |
TypeAlias
|
What a caller does with a state: follow, act, stop, or walk past. |
MERGE_STATES |
dict[str, tuple[MergeCategory, str]]
|
|
MergeCategory
module-attribute
¶
What a caller does with a state: follow, act, stop, or walk past.
MERGE_STATES
module-attribute
¶
MERGE_STATES: dict[str, tuple[MergeCategory, str]] = {'computing': ('in-progress', 'the forge is still computing mergeability'), 'ci-running': ('in-progress', 'required checks are still running'), 'approvals-syncing': ('in-progress', 'the forge is syncing approvals'), 'contexts-settling': ('in-progress', "the checks read green and the forge's protection view is catching up"), 'checks-red': ('recoverable', 'required checks are red: fix the failure and push'), 'behind': ('recoverable', 'the head is behind the base: integrate, then merge again'), 'conflict': ('recoverable', 'the branches conflict: resolve the conflicts and push'), 'draft': ('recoverable', 'the pull request is a draft: mark it ready'), 'approvals-missing': ('recoverable', 'required approvals are missing: an approver must approve'), 'changes-requested': ('recoverable', 'a reviewer requested changes: they must lift the request'), 'discussions-open': ('recoverable', 'open discussions remain: answer or resolve them'), 'blocked-by-dependency': ('recoverable', 'another merge request must merge first'), 'external-checks-pending': ('recoverable', 'an external status check must report success'), 'source-branch-missing': ('recoverable', 'the source branch is missing or empty: push the work'), 'reference-missing': ('recoverable', 'a required issue reference is missing: add it to the title or description'), 'merge-method-not-allowed': ('recoverable', "this merge method is not allowed here: use the repository's method"), 'hooks-refused': ('recoverable', 'a server-side hook refused the merge'), 'contexts-misreported': ('recoverable', "a required check context is reported by nothing: fix the required context's name to match what CI reports"), 'closed': ('terminal', 'the pull request is closed without merging'), 'merged': ('success', 'already merged')}
MergeState
dataclass
¶
MergeState(state: str, category: MergeCategory, message: str, native: str = '')
One classified merge hold.
Attributes:
| Name | Type | Description |
|---|---|---|
state |
str
|
The union vocabulary member ( |
category |
MergeCategory
|
What a caller does with it; see livery.forge.MergeCategory. |
message |
str
|
One user-facing sentence: the situation, and for a recoverable state what would recover it. |
native |
str
|
The forge's own words, verbatim; empty when the forge expressed the state as data rather than prose. |
merge_state ¶
merge_state(state: str, native: str = '') -> MergeState
The vocabulary member state, carrying native verbatim.
Source code in packages/forge/src/livery/forge/_merge_state.py
classify_gitlab_detailed_status ¶
classify_gitlab_detailed_status(value: str, *, item_state: ItemState = 'open', merged: bool = False) -> MergeState
GitLab's detailed_merge_status value as a merge state.
mergeable never reaches here: it is the go, not a hold.
not_open splits by the merged flag.
Source code in packages/forge/src/livery/forge/_merge_state.py
classify_github_mergeable_state ¶
classify_github_mergeable_state(value: str, *, item_state: ItemState = 'open', merged: bool = False) -> MergeState
GitHub's mergeable_state value as a merge state.
blocked folds required checks and missing approvals
together, which is as fine as GitHub's own data gets on this
path; the message stays the checks one, and the native value
rides along for the person reading.
Source code in packages/forge/src/livery/forge/_merge_state.py
classify_gitea_merge_refusal ¶
classify_gitea_merge_refusal(native: str, *, combined: CombinedStatus, item_state: ItemState, merged: bool) -> MergeState
Gitea's 405 prose as a merge state; the inputs disambiguate.
Gitea has no state field, so the message plus the checks API
decide. "Please try again later" is the mergeability recompute.
"Not all required status checks successful" is three states in
one sentence: red checks, checks still running, or the beat
where the protection view trails a green run; the combined
status tells them apart. A caller entering contexts-settling
should first verify every required context has a reporter,
because a context nothing reports never settles
(contexts-misreported); that cross-check needs the caller's
knowledge of reported context names.
Source code in packages/forge/src/livery/forge/_merge_state.py
classify_merge_refusal ¶
classify_merge_refusal(kind: str, native: str, *, combined: CombinedStatus, item_state: ItemState, merged: bool, hold: str = '') -> MergeState
Classify a merge-endpoint refusal by the forge kind.
The identity states resolve first on every forge: a merged pull
request is success whatever the words, a closed one terminal.
Gitea's prose classifier handles gitea and the empty kind
(the fake speaks Gitea's words). GitLab and GitHub classify
hold, their published state field read after the refusal
through livery.forge.PullRequests.merge_hold; a refusal
while that field already reads as the go (mergeable,
clean) is the recompute the refusal raced, and follows
through as computing. An empty hold on those forges is
unmapped: nothing waits on a state the forge did not publish.