Skip to content

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 completed runs carry a conclusion.

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=True on 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 the schedule trigger in the file.

RegistryKind module-attribute

RegistryKind: TypeAlias = Literal['python', 'conan', 'container']

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

CheckState: TypeAlias = Literal['none', 'pending', 'success', 'failure']

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

RunStatus: TypeAlias = Literal['queued', 'running', 'completed']

Where a run is in its life. Only completed runs carry a conclusion.

Conclusion module-attribute

Conclusion: TypeAlias = Literal['', 'success', 'failure', 'cancelled', 'skipped']

How a completed run or job ended. Empty until the run completes.

StateFilter module-attribute

StateFilter: TypeAlias = Literal['open', 'closed', 'all']

Which pull requests or issues a listing includes.

ItemState module-attribute

ItemState: TypeAlias = Literal['open', 'closed']

Where a pull request or issue is: open, or closed in any way.

ReviewState module-attribute

ReviewState: TypeAlias = Literal['approved', 'changes_requested', 'commented']

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

RateBudget(remaining: int, limit: int, reset_at: float | None = None)

The API budget a forge reports on its responses.

Attributes:

Name Type Description
remaining int

The requests left in the current window.

limit int

The requests the window allows.

reset_at float | None

When the window renews, as seconds since the epoch; None when the forge does not say.

remaining instance-attribute

remaining: int

limit instance-attribute

limit: int

reset_at class-attribute instance-attribute

reset_at: float | None = None

RepoInfo dataclass

RepoInfo(owner: str, name: str, default_branch: str, private: bool)

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.

owner instance-attribute

owner: str

name instance-attribute

name: str

default_branch instance-attribute

default_branch: str

private instance-attribute

private: bool

Label dataclass

Label(name: str, color: str, description: str = '')

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.

name instance-attribute

name: str

color instance-attribute

color: str

description class-attribute instance-attribute

description: str = ''

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 required_contexts capability raises livery.forge.Unsupported.

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 min_approvals capability.

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 ci_secrets capability raises livery.forge.Unsupported.

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.

default_branch class-attribute instance-attribute

default_branch: str | None = None

squash_only class-attribute instance-attribute

squash_only: bool | None = None

delete_branch_on_merge class-attribute instance-attribute

delete_branch_on_merge: bool | None = None

allow_auto_merge class-attribute instance-attribute

allow_auto_merge: bool | None = None

required_contexts class-attribute instance-attribute

required_contexts: tuple[str, ...] | None = None

protected_tag_patterns class-attribute instance-attribute

protected_tag_patterns: tuple[str, ...] | None = None

require_pipeline_success class-attribute instance-attribute

require_pipeline_success: bool | None = None

min_approvals class-attribute instance-attribute

min_approvals: int | None = None

require_codeowner_review class-attribute instance-attribute

require_codeowner_review: bool | None = None

secrets class-attribute instance-attribute

secrets: Mapping[str, str] | None = None

variables class-attribute instance-attribute

variables: Mapping[str, str] | None = None

labels class-attribute instance-attribute

labels: tuple[Label, ...] | 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

open or closed. A merged pull request is closed with merged True.

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.

number instance-attribute

number: int

title instance-attribute

title: str

body instance-attribute

body: str

state instance-attribute

state: ItemState

merged instance-attribute

merged: bool

head_branch instance-attribute

head_branch: str

head_sha instance-attribute

head_sha: str

base_branch instance-attribute

base_branch: str

url class-attribute instance-attribute

url: str = ''

author class-attribute instance-attribute

author: str = ''

merged_sha class-attribute instance-attribute

merged_sha: str = ''

labels class-attribute instance-attribute

labels: tuple[str, ...] = ()

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. none when nothing has reported for the commit, which is not pending: see livery.forge.CheckState.

contexts int

How many checks the verdict aggregates. Zero exactly when state is none.

state instance-attribute

state: CheckState

contexts instance-attribute

contexts: int

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 livery.forge.Checks method takes. Backends that also number runs per repository translate; the protocol speaks one handle.

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 $FORGE_WORKFLOW so a dispatched pipeline carries the workflow asked for, and empty for a pipeline the document does not name.

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 status is completed.

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 (main, v1.2.0): the head branch GitHub and Gitea name, the ref GitLab names. A caller that dispatched a workflow on a ref tells its run from another ref's by this. Empty when the forge did not say.

id instance-attribute

id: int

workflow instance-attribute

workflow: str

head_sha instance-attribute

head_sha: str

event instance-attribute

event: str

status instance-attribute

status: RunStatus

conclusion instance-attribute

conclusion: Conclusion

url class-attribute instance-attribute

url: str = ''

created_at class-attribute instance-attribute

created_at: str = ''

started_at class-attribute instance-attribute

started_at: str = ''

completed_at class-attribute instance-attribute

completed_at: str = ''

ref class-attribute instance-attribute

ref: str = ''

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.

name instance-attribute

name: str

conclusion instance-attribute

conclusion: Conclusion

started_at class-attribute instance-attribute

started_at: str = ''

completed_at class-attribute instance-attribute

completed_at: str = ''

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 status is completed.

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.

id instance-attribute

id: int

name instance-attribute

name: str

status instance-attribute

status: RunStatus

conclusion instance-attribute

conclusion: Conclusion

started_at class-attribute instance-attribute

started_at: str = ''

completed_at class-attribute instance-attribute

completed_at: str = ''

steps class-attribute instance-attribute

steps: tuple[Step, ...] = ()

Release dataclass

Release(tag: str, name: str, body: str, prerelease: bool = False, url: str = '', id: int = 0)

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.

tag instance-attribute

tag: str

name instance-attribute

name: str

body instance-attribute

body: str

prerelease class-attribute instance-attribute

prerelease: bool = False

url class-attribute instance-attribute

url: str = ''

id class-attribute instance-attribute

id: int = 0

Asset dataclass

Asset(name: str, url: str, size: int = 0, digest: str = '')

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, "<algorithm>:<hex>"; empty when it reports none. A consumer that stages the bytes elsewhere verifies against it, and treats an empty digest as a forge that cannot prove the content.

name instance-attribute

name: str

url instance-attribute

url: str

size class-attribute instance-attribute

size: int = 0

digest class-attribute instance-attribute

digest: str = ''

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

open or closed.

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.

number instance-attribute

number: int

title instance-attribute

title: str

body instance-attribute

body: str

state instance-attribute

state: ItemState

labels class-attribute instance-attribute

labels: tuple[str, ...] = ()

assignees class-attribute instance-attribute

assignees: tuple[str, ...] = ()

url class-attribute instance-attribute

url: str = ''

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.

author instance-attribute

author: str

state instance-attribute

state: ReviewState

Comment dataclass

Comment(author: str, created_at: str, body: str)

One comment on an issue's thread.

Attributes:

Name Type Description
author str

The login of who wrote it, the same namespace as livery.forge.Forge.whoami.

created_at str

When it was posted, as the forge reports it; empty when the forge does not say.

body str

The comment text, in full.

author instance-attribute

author: str

created_at instance-attribute

created_at: str

body instance-attribute

body: str

CodeownersEntry dataclass

CodeownersEntry(path: str, owners: tuple[str, ...], min_approvals: int = 0)

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, / separators).

owners tuple[str, ...]

User logins and team names, without any @ sigil; the backend adds its forge's spelling.

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.

path instance-attribute

path: str

owners instance-attribute

owners: tuple[str, ...]

min_approvals class-attribute instance-attribute

min_approvals: int = 0

Codeowners dataclass

Codeowners(path: str, content: str, notes: tuple[str, ...] = ())

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.

path instance-attribute

path: str

content instance-attribute

content: str

notes class-attribute instance-attribute

notes: tuple[str, ...] = ()

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.

required_approvals class-attribute instance-attribute

required_approvals: int = 0

require_codeowner_review class-attribute instance-attribute

require_codeowner_review: bool | None = None

block_on_outdated class-attribute instance-attribute

block_on_outdated: bool = False

block_on_rejected class-attribute instance-attribute

block_on_rejected: bool = False

required_contexts class-attribute instance-attribute

required_contexts: tuple[str, ...] = ()

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.

id instance-attribute

id: int

description instance-attribute

description: str

ref instance-attribute

ref: str

cron instance-attribute

cron: str

active class-attribute instance-attribute

active: bool = True

variables class-attribute instance-attribute

variables: tuple[tuple[str, str], ...] = ()

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.

kind instance-attribute

actor class-attribute instance-attribute

actor: str = ''

created class-attribute instance-attribute

created: str = ''