livery.forge._types¶
livery.forge._types ¶
The values the protocol speaks: literal vocabularies and frozen records.
Every record is immutable and forge-neutral. A backend translates its server's shapes into these at the boundary and never lets a native field leak through. Numbers identify pull requests, issues, runs, and jobs; each kind numbers its own space, so a pull request number must never be used as an issue number or the reverse. GitLab keeps the spaces separate, so the protocol does too.
Classes:
| Name | Description |
|---|---|
RateBudget |
The API budget a forge reports on its responses. |
RepoInfo |
What livery.forge.Forge.get_repo reports about an existing repository. |
Label |
One issue label, spoken by name everywhere. |
RepoConfig |
The desired repository settings livery.forge.Repository.configure asserts. |
PullRequest |
One pull request, as the forge reports it. |
CombinedStatus |
The one CI answer for a commit, whatever the forge calls it underneath. |
Run |
One CI run: a workflow run on GitHub or Gitea, a pipeline on GitLab. |
Step |
One step of a job, as the forge times it. |
Job |
One job of a run. |
Release |
One release, addressed by its tag. |
Asset |
One file attached to a release. |
Issue |
One issue, body included. |
Review |
One submitted pull request review. |
Comment |
One comment on an issue's thread. |
CodeownersEntry |
One neutral ownership declaration a codeowners file expresses. |
Codeowners |
A rendered codeowners file: where it lives and what it says. |
Protection |
The branch protection a forge reports for one branch. |
Schedule |
One pipeline schedule: the forge's clock for a workflow the file cannot time. |
ScheduleEvent |
One event in a pull request's merge-scheduling history. |
Attributes:
| Name | Type | Description |
|---|---|---|
Capability |
TypeAlias
|
What livery.forge.Forge.supports answers for, by name. |
RegistryKind |
TypeAlias
|
The artifact registries the ecosystem speaks, by protocol. |
CheckState |
TypeAlias
|
The combined verdict for one commit. |
RunStatus |
TypeAlias
|
Where a run is in its life. Only |
Conclusion |
TypeAlias
|
How a completed run or job ended. Empty until the run completes. |
StateFilter |
TypeAlias
|
Which pull requests or issues a listing includes. |
ItemState |
TypeAlias
|
Where a pull request or issue is: open, or closed in any way. |
ReviewState |
TypeAlias
|
A submitted review's verdict, normalised across the forges. |
ScheduleEventKind |
TypeAlias
|
What happened to a pull request's merge schedule, normalised. |
Capability
module-attribute
¶
Capability: TypeAlias = Literal['auto_merge', 'force_cancel', 'required_contexts', 'ci_secrets', 'schedule_events', 'min_approvals', 'pages_config', 'pipeline_schedules']
What livery.forge.Forge.supports answers for, by name.
auto_merge: the forge can schedule a merge that fires when the checks go green (livery.forge.PullRequests.arm).force_cancel: the forge can cancel a run whose runner stopped answering (force=Trueon livery.forge.Checks.cancel_run).required_contexts: branch protection can name the check contexts that must pass before a merge.ci_secrets: livery.forge.RepoConfig.secrets can be stored through the backend. GitHub's backend declines: its secrets API demands sealed-box encryption the standard library cannot provide, and no workflow stores a secret there, because trusted publishing replaces tokens on GitHub.min_approvals: protection can require a number of approving reviews (and a codeowner's), applied by livery.forge.Repository.configure. GitLab ties required approval rules to paid tiers, so its backend declines; the decline is what keeps a one-assignee, one-approver policy honest there.schedule_events: the merge-scheduling history of a pull request can be read back (livery.forge.PullRequests.schedule_events). GitLab's backend declines: its system notes carry no reliable scheduling record.pages_config: the forge's static-site hosting can be enabled through the API (livery.forge.Repository.ensure_pages). Only GitHub has one to configure: Gitea ships no Pages, and GitLab Pages exists implicitly through pipeline artifacts.pipeline_schedules: the forge keeps the clock outside the workflow file, as a project setting the API creates (livery.forge.Repository.schedule). GitLab's pipeline schedules are that; GitHub and Gitea decline, since their clock is thescheduletrigger in the file.
RegistryKind
module-attribute
¶
The artifact registries the ecosystem speaks, by protocol.
python is the simple index and its upload endpoint; conan
is a conan 2 remote; container is an OCI distribution registry.
The handles that speak these protocols are host-generic: any server
or folder speaking the protocol works. A forge answers which of
them it hosts through livery.forge.Forge.registry_url.
CheckState
module-attribute
¶
The combined verdict for one commit.
none means nothing has reported for the commit at all, which must
stay distinguishable from pending: a commit no run ever started on
looks identical to a live run otherwise, and a poll loop would wait on
it forever.
RunStatus
module-attribute
¶
Where a run is in its life. Only completed runs carry a conclusion.
Conclusion
module-attribute
¶
How a completed run or job ended. Empty until the run completes.
StateFilter
module-attribute
¶
Which pull requests or issues a listing includes.
ItemState
module-attribute
¶
Where a pull request or issue is: open, or closed in any way.
ReviewState
module-attribute
¶
A submitted review's verdict, normalised across the forges.
Only approved and changes_requested decide anything; a
commented review supersedes nothing. Unsubmitted drafts are never
reported.
ScheduleEventKind
module-attribute
¶
ScheduleEventKind: TypeAlias = Literal['scheduled', 'unscheduled', 'merged', 'closed', 'reopened', 'pushed']
What happened to a pull request's merge schedule, normalised.
RateBudget
dataclass
¶
RepoInfo
dataclass
¶
What livery.forge.Forge.get_repo reports about an existing repository.
Attributes:
| Name | Type | Description |
|---|---|---|
owner |
str
|
The user, organisation, or group path that owns the repository. |
name |
str
|
The repository name within the owner. |
default_branch |
str
|
The branch pull requests target by default. |
private |
bool
|
True when the repository is not publicly visible. |
Label
dataclass
¶
One issue label, spoken by name everywhere.
The protocol never exposes label ids: backends that key labels by id resolve the name at the boundary.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The label text, unique within the repository. |
color |
str
|
Six hex digits, no leading |
description |
str
|
One line saying when the label applies. |
RepoConfig
dataclass
¶
RepoConfig(default_branch: str | None = None, squash_only: bool | None = None, delete_branch_on_merge: bool | None = None, allow_auto_merge: bool | None = None, required_contexts: tuple[str, ...] | None = None, protected_tag_patterns: tuple[str, ...] | None = None, require_pipeline_success: bool | None = None, min_approvals: int | None = None, require_codeowner_review: bool | None = None, secrets: Mapping[str, str] | None = None, variables: Mapping[str, str] | None = None, labels: tuple[Label, ...] | None = None)
The desired repository settings livery.forge.Repository.configure asserts.
Every field defaults to None, which means "leave this setting as it is". Configure applies only the fields a caller states, so one config value can repair one drifted setting without touching the rest.
Attributes:
| Name | Type | Description |
|---|---|---|
default_branch |
str | None
|
The branch pull requests target by default. |
squash_only |
bool | None
|
True allows only squash merges. |
delete_branch_on_merge |
bool | None
|
True deletes a pull request's head branch when it merges. |
allow_auto_merge |
bool | None
|
True lets a merge be scheduled to fire when the checks go green. |
required_contexts |
tuple[str, ...] | None
|
The check contexts the default branch's
protection requires before a merge. Setting this on a
forge without the |
require_pipeline_success |
bool | None
|
True makes the server refuse merges while the head's checks are not green, for everyone, the forge's own UI included. GitHub and Gitea already enforce exactly this through required_contexts and ignore the field; GitLab maps it to its merge-only-when-the-pipeline-succeeds switch, the one server-side block its protection offers. On a repository with several pipeline sources that switch blocks on any red pipeline, which is as precise as GitLab's data gets. |
min_approvals |
int | None
|
Approving reviews the default branch's
protection requires before a merge. Applied with admins
bound: protection that exempts admins is a bypass nobody
reviewed, so configure never leaves one open. Needs the
|
require_codeowner_review |
bool | None
|
True also requires an approval from a codeowner of the touched paths. Rides the same capability. Gitea has no codeowner toggle and substitutes blocking on official review requests, which the codeowners file feeds; the read side answers through the same field. |
protected_tag_patterns |
tuple[str, ...] | None
|
Tag name patterns (glob) whose tags, once created, cannot be deleted or re-pointed by an ordinary push. Who may create them follows each forge's nearest model: GitLab restricts creation to maintainers and blocks push-deletion for everyone (the web interface with a deliberate unprotect is the only way); GitHub leaves creation open and blocks deletion and movement through a tag ruleset; Gitea ties creation, deletion, and movement to one whitelist holding the configuring identity, so its protection binds everyone outside that lane rather than the lane itself. Patterns already protected are left as they are. |
secrets |
Mapping[str, str] | None
|
CI secrets to store, by name. Write-only: no protocol
operation reads a secret back. Setting this on a forge
without the |
variables |
Mapping[str, str] | None
|
Plain CI variables to store, by name. |
labels |
tuple[Label, ...] | None
|
The labels the repository must offer. Labels already present keep their issues; labels absent from this tuple are left alone, never deleted. |
delete_branch_on_merge
class-attribute
instance-attribute
¶
delete_branch_on_merge: bool | None = None
required_contexts
class-attribute
instance-attribute
¶
protected_tag_patterns
class-attribute
instance-attribute
¶
require_pipeline_success
class-attribute
instance-attribute
¶
require_pipeline_success: bool | None = None
PullRequest
dataclass
¶
PullRequest(number: int, title: str, body: str, state: ItemState, merged: bool, head_branch: str, head_sha: str, base_branch: str, url: str = '', author: str = '', merged_sha: str = '', labels: tuple[str, ...] = ())
One pull request, as the forge reports it.
Attributes:
| Name | Type | Description |
|---|---|---|
number |
int
|
The number a person sees in the forge's own UI. On GitLab this is the merge request iid, never the global id. |
title |
str
|
The pull request title. |
body |
str
|
The pull request description, in full. |
state |
ItemState
|
|
merged |
bool
|
True when the pull request has merged. |
head_branch |
str
|
The branch the pull request proposes. May be empty on a merged pull request whose head branch was deleted; find a merged pull request by livery.forge.PullRequests.find_by_head_sha instead. |
head_sha |
str
|
The head commit. Persists after the branch is gone. |
base_branch |
str
|
The branch the pull request targets. |
url |
str
|
The pull request's page, for printing to a person. |
author |
str
|
The login of whoever opened it; empty when the forge does not say. Compare with livery.forge.Forge.whoami, the same namespace. |
merged_sha |
str
|
The commit the merge produced, empty until it has merged. On a squash-only repository this is the squash, and it is the only way to follow a pull request into what ran on the base afterwards: the base's own runs are filed under this commit, and nothing on the pull request itself names it. |
labels |
tuple[str, ...]
|
The label names on the pull request, as livery.forge.PullRequests.add_labels sets them and a person sets them on the forge. |
CombinedStatus
dataclass
¶
CombinedStatus(state: CheckState, contexts: int)
The one CI answer for a commit, whatever the forge calls it underneath.
GitHub folds check runs and commit statuses into it, Gitea aggregates commit statuses, GitLab reports the commit's latest pipeline. The caller sees one verdict either way.
Attributes:
| Name | Type | Description |
|---|---|---|
state |
CheckState
|
The combined verdict. |
contexts |
int
|
How many checks the verdict aggregates. Zero exactly
when |
Run
dataclass
¶
Run(id: int, workflow: str, head_sha: str, event: str, status: RunStatus, conclusion: Conclusion, url: str = '', created_at: str = '', started_at: str = '', completed_at: str = '', ref: str = '')
One CI run: a workflow run on GitHub or Gitea, a pipeline on GitLab.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
The identifier every |
workflow |
str
|
The workflow that ran, as the forge names it. A
workflow file name on GitHub and Gitea; on GitLab, which
has one pipeline definition per repository, the pipeline's
name, which a document sets from |
head_sha |
str
|
The commit the run checked. |
event |
str
|
What triggered the run, in the forge's own vocabulary. |
status |
RunStatus
|
Where the run is in its life. |
conclusion |
Conclusion
|
How the run ended. Empty until |
url |
str
|
The run's page, for printing to a person. |
created_at |
str
|
When the forge accepted the run, ISO 8601; the queue wait starts here. Empty when the forge did not say. |
started_at |
str
|
When the first job started, the same way. GitLab's pipeline listing does not carry it. |
completed_at |
str
|
When the run ended, the same way. GitHub reports no end for a run; its last update stands in once the run is complete. |
ref |
str
|
The branch or tag the run checked out, by its short name
( |
Step
dataclass
¶
Step(name: str, conclusion: Conclusion, started_at: str = '', completed_at: str = '')
One step of a job, as the forge times it.
GitHub and Gitea time every step, the runner's own setup and teardown included; GitLab runs a job as one script and serves no steps.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The step's name as the workflow spells it, or the runner's name for a step it adds itself. |
conclusion |
Conclusion
|
How the step ended. Empty while it runs. |
started_at |
str
|
When it started, ISO 8601. Empty when the forge did not say. |
completed_at |
str
|
When it ended, the same way. |
Job
dataclass
¶
Job(id: int, name: str, status: RunStatus, conclusion: Conclusion, started_at: str = '', completed_at: str = '', steps: tuple[Step, ...] = ())
One job of a run.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
The identifier livery.forge.Checks.job_log takes. |
name |
str
|
The job name as the workflow declares it. |
status |
RunStatus
|
Where the job is in its life. |
conclusion |
Conclusion
|
How the job ended. Empty until |
started_at |
str
|
When the job started on a runner, ISO 8601. Empty until it has, or when the forge did not say. |
completed_at |
str
|
When it ended, the same way. |
steps |
tuple[Step, ...]
|
The job's steps with their times, in order; empty on a forge that serves none. |
Release
dataclass
¶
One release, addressed by its tag.
Attributes:
| Name | Type | Description |
|---|---|---|
tag |
str
|
The tag the release describes. The tag is the identity; the release is its prose. |
name |
str
|
The display name. |
body |
str
|
The release notes, in full. |
prerelease |
bool
|
True when the release is marked as a prerelease. |
url |
str
|
The release's page, for printing to a person. |
id |
int
|
The forge's own number for the release, for the calls that address a release by it (an asset upload); 0 on a forge that addresses releases by tag alone. |
Asset
dataclass
¶
One file attached to a release.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The file name, unique within the release. |
url |
str
|
Where the bytes download from, for a reader with access to the repository. |
size |
int
|
The byte count the forge reports; 0 when it reports none. |
digest |
str
|
The content digest the forge reports, |
Issue
dataclass
¶
Issue(number: int, title: str, body: str, state: ItemState, labels: tuple[str, ...] = (), assignees: tuple[str, ...] = (), url: str = '')
One issue, body included.
Attributes:
| Name | Type | Description |
|---|---|---|
number |
int
|
The number a person sees in the forge's own UI. On GitLab this is the issue iid, never the global id. |
title |
str
|
The issue title. |
body |
str
|
The issue text, in full. The body is the work order for issue-driven workflows, so it is always carried, never truncated. |
state |
ItemState
|
|
labels |
tuple[str, ...]
|
The label names on the issue. |
assignees |
tuple[str, ...]
|
The login names assigned to the issue. |
url |
str
|
The issue's page, for printing to a person. |
Review
dataclass
¶
Review(author: str, state: ReviewState)
One submitted pull request review.
Attributes:
| Name | Type | Description |
|---|---|---|
author |
str
|
The login of the reviewer, the same namespace as livery.forge.Forge.whoami. |
state |
ReviewState
|
The verdict, per livery.forge.ReviewState. |
Comment
dataclass
¶
CodeownersEntry
dataclass
¶
One neutral ownership declaration a codeowners file expresses.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The repository path the owners review (a directory or
glob, forge-neutral, |
owners |
tuple[str, ...]
|
User logins and team names, without any |
min_approvals |
int
|
Approvals this path needs. Only GitLab's sections express a per-path count in the file itself; the other forges approximate through protection and say so in the rendering's notes. |
Codeowners
dataclass
¶
A rendered codeowners file: where it lives and what it says.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The forge's canonical location for the file, relative to the repository root. |
content |
str
|
The file's text in the forge's syntax. |
notes |
tuple[str, ...]
|
What the rendering approximated rather than expressed, one sentence each; empty when everything was expressed. |
Protection
dataclass
¶
Protection(required_approvals: int = 0, require_codeowner_review: bool | None = None, block_on_outdated: bool = False, block_on_rejected: bool = False, required_contexts: tuple[str, ...] = ())
The branch protection a forge reports for one branch.
The read side of livery.forge.RepoConfig, normalised and honest: a field a forge cannot express reads as its inert value, so a caller gating on a flag never invents a blocker the forge would not enforce.
Attributes:
| Name | Type | Description |
|---|---|---|
required_approvals |
int
|
Approving reviews the merge requires; 0 when none. |
require_codeowner_review |
bool | None
|
True when a codeowner's approval is required; None when the forge cannot say. |
block_on_outdated |
bool
|
True when a head behind its base may not merge. |
block_on_rejected |
bool
|
True when a requested-changes review blocks the merge. |
required_contexts |
tuple[str, ...]
|
The check contexts protection requires. |
Schedule
dataclass
¶
Schedule(id: int, description: str, ref: str, cron: str, active: bool = True, variables: tuple[tuple[str, str], ...] = ())
One pipeline schedule: the forge's clock for a workflow the file cannot time.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
The forge's identifier of the schedule. |
description |
str
|
The name a caller addresses it by; unique per repository as livery.forge.Schedules keeps it. |
ref |
str
|
The branch the scheduled pipeline runs on. |
cron |
str
|
When it runs, in cron's five fields, UTC. |
active |
bool
|
Whether the clock is on. |
variables |
tuple[tuple[str, str], ...]
|
The variables each scheduled pipeline starts with, as (key, value) pairs in the forge's order. |
ScheduleEvent
dataclass
¶
ScheduleEvent(kind: ScheduleEventKind, actor: str = '', created: str = '')
One event in a pull request's merge-scheduling history.
The record that shows a created-then-lost schedule, which no
current-state read can. Available only where the forge keeps the
history (the schedule_events capability).
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
ScheduleEventKind
|
What happened, per livery.forge.ScheduleEventKind. |
actor |
str
|
The login that caused it; empty when the forge does not say. |
created |
str
|
When it happened, the forge's own timestamp string. |