Skip to content

livery.forge._protocol

livery.forge._protocol

The protocols every backend implements and every workflow calls.

livery.forge.Forge is one server: identity, capabilities, and the repositories it hosts. livery.forge.Repository is one repository on that server, with its operations grouped the way the workflows name them: pr, checks, issue, release. livery.forge.Registry is a package index, kept apart because a forge and a registry are only sometimes the same server.

Four rules hold across every method:

  • One handle. A pull request, issue, run, or job is identified by the number or id the protocol returned for it. A backend whose server keeps two identities (GitLab's iid and global id) translates at the boundary and never leaks the other one.
  • Listings are complete or they raise. A method that returns a sequence returns everything the query matches. When a backend cannot read to the end (a pagination cap, a truncated answer), it raises livery.forge.ForgeError instead of returning a prefix, because "not in this list" is an answer callers act on.
  • Probe before acting. Every verb is safe to re-run, and re-running a workflow is its recovery procedure. Where an operation is not idempotent on the server (creating a release, opening a pull request), the protocol pairs it with the read that makes the caller's probe-then-act loop idempotent.
  • Capabilities, not pretence. Where forges differ, the difference is a named livery.forge.Capability. A backend asked for an operation it declined by name raises livery.forge.Unsupported; callers that can degrade probe livery.forge.Forge.supports first.

Failures carry the server's own words: every livery.forge.ForgeError message quotes what the server said, and no failure is ever reduced to a bare boolean.

Classes:

Name Description
PullRequests

One repository's pull requests: open, find, merge, arm, comment.

Checks

One repository's CI: the combined verdict, runs, jobs, and logs.

Schedules

One repository's pipeline schedules, addressed by description.

Releases

One repository's releases, addressed by tag.

Issues

One repository's issues: text in both directions.

Repository

One repository on one forge.

Forge

One forge server: identity, capabilities, and its repositories.

Registry

One package index, apart from the forge.

PullRequests

Bases: Protocol

One repository's pull requests: open, find, merge, arm, comment.

GitLab calls them merge requests; the operations map one to one and the protocol keeps one vocabulary.

Methods:

Name Description
open

Open a pull request from head into base and return it.

find_by_head

The pull request whose head branch is branch, or None.

find_by_head_sha

The pull request whose head commit is sha, or None.

get

The pull request number, or None when it does not exist.

list

The repository's pull requests in state, newest first.

update_title

Retitle pull request number.

update_body

Replace the description of pull request number.

close

Close pull request number without merging.

reopen

Reopen the closed, unmerged pull request number.

merge_now

Merge pull request number immediately.

arm

Schedule pull request number to merge when its checks go green.

disarm

Cancel a scheduled merge on pull request number.

is_armed

Whether pull request number currently has a merge scheduled.

merge_hold

The forge's published mergeability state of number, verbatim.

reviews

The submitted reviews on pull request number.

schedule_events

The merge-scheduling history of pull request number.

comment

Post body as a comment on pull request number.

add_labels

Put the labels names on pull request number.

open

open(head: str, base: str, title: str, body: str = '') -> PullRequest

Open a pull request from head into base and return it.

Raises livery.forge.ForgeError when an open pull request for head already exists; find and reuse it with livery.forge.PullRequests.find_by_head first.

Source code in packages/forge/src/livery/forge/_protocol.py
def open(self, head: str, base: str, title: str, body: str = "") -> PullRequest:
    """Open a pull request from *head* into *base* and return it.

    Raises livery.forge.ForgeError when an open pull request for
    *head* already exists; find and reuse it with
    livery.forge.PullRequests.find_by_head first.
    """
    ...

find_by_head

find_by_head(branch: str, *, state: StateFilter = 'open') -> PullRequest | None

The pull request whose head branch is branch, or None.

Reliable for open pull requests. A merged pull request whose head branch was auto-deleted may no longer carry the branch name on some forges, so "None" here does not prove no such pull request ever existed: find a finished one by livery.forge.PullRequests.find_by_head_sha instead.

Source code in packages/forge/src/livery/forge/_protocol.py
def find_by_head(
    self, branch: str, *, state: StateFilter = "open"
) -> PullRequest | None:
    """The pull request whose head branch is *branch*, or None.

    Reliable for open pull requests. A merged pull request whose
    head branch was auto-deleted may no longer carry the branch
    name on some forges, so "None" here does not prove no such
    pull request ever existed: find a finished one by
    livery.forge.PullRequests.find_by_head_sha instead.
    """
    ...

find_by_head_sha

find_by_head_sha(sha: str) -> PullRequest | None

The pull request whose head commit is sha, or None.

The head sha outlives the head branch, so this finds a merged pull request after the branch is gone.

Source code in packages/forge/src/livery/forge/_protocol.py
def find_by_head_sha(self, sha: str) -> PullRequest | None:
    """The pull request whose head commit is *sha*, or None.

    The head sha outlives the head branch, so this finds a merged
    pull request after the branch is gone.
    """
    ...

get

get(number: int) -> PullRequest | None

The pull request number, or None when it does not exist.

Source code in packages/forge/src/livery/forge/_protocol.py
def get(self, number: int) -> PullRequest | None:
    """The pull request *number*, or None when it does not exist."""
    ...

list

list(*, state: StateFilter = 'open') -> tuple[PullRequest, ...]

The repository's pull requests in state, newest first.

closed holds the merged pull requests and the ones closed without merging, as livery.forge.PullRequests.find_by_head reads the filter; merged tells the two apart. Each row carries the fields livery.forge.PullRequests.get answers for its number. Complete or raising, like every listing.

Source code in packages/forge/src/livery/forge/_protocol.py
def list(self, *, state: StateFilter = "open") -> tuple[PullRequest, ...]:
    """The repository's pull requests in *state*, newest first.

    ``closed`` holds the merged pull requests and the ones closed
    without merging, as [livery.forge.PullRequests.find_by_head][]
    reads the filter; ``merged`` tells the two apart. Each row
    carries the fields [livery.forge.PullRequests.get][] answers
    for its number. Complete or raising, like every listing.
    """
    ...

update_title

update_title(number: int, title: str) -> None

Retitle pull request number.

The title is the review-facing name and, on a squash-only repository, the merge armed after this call carries it as the commit subject.

Source code in packages/forge/src/livery/forge/_protocol.py
def update_title(self, number: int, title: str) -> None:
    """Retitle pull request *number*.

    The title is the review-facing name and, on a squash-only
    repository, the merge armed after this call carries it as the
    commit subject.
    """
    ...

update_body

update_body(number: int, body: str) -> None

Replace the description of pull request number.

The body is the review-facing text and, on a squash-only repository, the merge armed after this call carries it as the commit message.

Source code in packages/forge/src/livery/forge/_protocol.py
def update_body(self, number: int, body: str) -> None:
    """Replace the description of pull request *number*.

    The body is the review-facing text and, on a squash-only
    repository, the merge armed after this call carries it as the
    commit message.
    """
    ...

close

close(number: int) -> None

Close pull request number without merging.

Source code in packages/forge/src/livery/forge/_protocol.py
def close(self, number: int) -> None:
    """Close pull request *number* without merging."""
    ...

reopen

reopen(number: int) -> None

Reopen the closed, unmerged pull request number.

Reopening reuses the pull request, history and discussion intact, rather than opening a duplicate.

Source code in packages/forge/src/livery/forge/_protocol.py
def reopen(self, number: int) -> None:
    """Reopen the closed, unmerged pull request *number*.

    Reopening reuses the pull request, history and discussion
    intact, rather than opening a duplicate.
    """
    ...

merge_now

merge_now(number: int, *, title: str, message: str = '') -> None

Merge pull request number immediately.

title is the squash commit subject, message its body. A refusal raises livery.forge.ForgeError with the status a caller branches on: 405 when the checks are not green, 409 on a conflict. A caller that can wait arms instead (livery.forge.PullRequests.arm).

Merging an already merged pull request is success: re-running a verb is its recovery procedure, and backends whose forge refuses the second merge absorb that refusal after verifying the pull request really merged.

Source code in packages/forge/src/livery/forge/_protocol.py
def merge_now(self, number: int, *, title: str, message: str = "") -> None:
    """Merge pull request *number* immediately.

    *title* is the squash commit subject, *message* its body. A
    refusal raises livery.forge.ForgeError with the status a
    caller branches on: 405 when the checks are not green, 409 on
    a conflict. A caller that can wait arms instead
    (livery.forge.PullRequests.arm).

    Merging an already merged pull request is success: re-running
    a verb is its recovery procedure, and backends whose forge
    refuses the second merge absorb that refusal after verifying
    the pull request really merged.
    """
    ...

arm

arm(number: int, *, title: str, message: str = '') -> None

Schedule pull request number to merge when its checks go green.

title is the squash commit subject the merge will carry, message its body. A forge that limits the subject's length carries a longer one cut at a word boundary, so a long title never stops the arm: livery.forge.GithubForge cuts at 320 UTF-8 bytes. Arming an already armed pull request replaces the schedule, title included. The merge itself happens server-side: the caller observes it through livery.forge.Checks.status and livery.forge.PullRequests.get, never performs it. Push to an armed pull request only after livery.forge.PullRequests.disarm: a push into a live schedule races the merge, and the merge can take the pre-push head.

Raises livery.forge.Unsupported on a forge without the auto_merge capability.

Source code in packages/forge/src/livery/forge/_protocol.py
def arm(self, number: int, *, title: str, message: str = "") -> None:
    """Schedule pull request *number* to merge when its checks go green.

    *title* is the squash commit subject the merge will carry,
    *message* its body. A forge that limits the subject's length
    carries a longer one cut at a word boundary, so a long title
    never stops the arm: [livery.forge.GithubForge][] cuts at 320
    UTF-8 bytes. Arming an already armed pull request replaces
    the schedule, title included. The merge itself
    happens server-side: the caller observes it through
    livery.forge.Checks.status and livery.forge.PullRequests.get,
    never performs it. Push to an armed pull request only after
    livery.forge.PullRequests.disarm: a push into a live schedule
    races the merge, and the merge can take the pre-push head.

    Raises livery.forge.Unsupported on a forge without the
    ``auto_merge`` capability.
    """
    ...

disarm

disarm(number: int) -> bool

Cancel a scheduled merge on pull request number.

Returns True when a schedule was cancelled and False when there was nothing to cancel. Idempotent: disarming an unarmed pull request is not an error.

Source code in packages/forge/src/livery/forge/_protocol.py
def disarm(self, number: int) -> bool:
    """Cancel a scheduled merge on pull request *number*.

    Returns True when a schedule was cancelled and False when there
    was nothing to cancel. Idempotent: disarming an unarmed pull
    request is not an error.
    """
    ...

is_armed

is_armed(number: int) -> bool

Whether pull request number currently has a merge scheduled.

A pull request that left the open state reads unarmed, however it left it.

Source code in packages/forge/src/livery/forge/_protocol.py
def is_armed(self, number: int) -> bool:
    """Whether pull request *number* currently has a merge scheduled.

    A pull request that left the open state reads unarmed, however
    it left it.
    """
    ...

merge_hold

merge_hold(number: int) -> str

The forge's published mergeability state of number, verbatim.

GitLab's detailed_merge_status and GitHub's mergeable_state; empty on a forge that publishes none (Gitea says why in the merge refusal's prose instead). livery.forge.classify_merge_refusal reads it to classify a refusal on those forges. Raises livery.forge.ForgeError with status 404 when the pull request does not exist.

Source code in packages/forge/src/livery/forge/_protocol.py
def merge_hold(self, number: int) -> str:
    """The forge's published mergeability state of *number*, verbatim.

    GitLab's ``detailed_merge_status`` and GitHub's
    ``mergeable_state``; empty on a forge that publishes none
    (Gitea says why in the merge refusal's prose instead).
    [livery.forge.classify_merge_refusal][] reads it to classify a
    refusal on those forges. Raises livery.forge.ForgeError with
    status 404 when the pull request does not exist.
    """
    ...

reviews

reviews(number: int) -> tuple[Review, ...]

The submitted reviews on pull request number.

Only verdicts arrive (approved, changes requested, commented); drafts never do. Complete or raising, like every listing.

Source code in packages/forge/src/livery/forge/_protocol.py
def reviews(self, number: int) -> tuple[Review, ...]:
    """The submitted reviews on pull request *number*.

    Only verdicts arrive (approved, changes requested, commented);
    drafts never do. Complete or raising, like every listing.
    """
    ...

schedule_events

schedule_events(number: int) -> tuple[ScheduleEvent, ...]

The merge-scheduling history of pull request number.

Oldest first. The record that shows a created-then-lost schedule. Raises livery.forge.Unsupported on a forge without the schedule_events capability; ask livery.forge.Forge.supports first.

Source code in packages/forge/src/livery/forge/_protocol.py
def schedule_events(self, number: int) -> tuple[ScheduleEvent, ...]:
    """The merge-scheduling history of pull request *number*.

    Oldest first. The record that shows a created-then-lost
    schedule. Raises livery.forge.Unsupported on a forge without
    the ``schedule_events`` capability; ask
    livery.forge.Forge.supports first.
    """
    ...

comment

comment(number: int, body: str) -> None

Post body as a comment on pull request number.

The evidence channel: conflict reports and failure summaries that the pull request body cannot carry land here.

Source code in packages/forge/src/livery/forge/_protocol.py
def comment(self, number: int, body: str) -> None:
    """Post *body* as a comment on pull request *number*.

    The evidence channel: conflict reports and failure summaries
    that the pull request body cannot carry land here.
    """
    ...

add_labels

add_labels(number: int, names: tuple[str, ...]) -> None

Put the labels names on pull request number.

Adds to the labels the pull request carries; a name already on it stays, so a re-run is the recovery procedure. Every name must already be a label of the repository: one that is not raises livery.forge.ForgeError naming it, before anything is written, on every backend. Ensure the labels exist first with livery.forge.Repository.configure. A number that names no pull request raises livery.forge.ForgeError with status 404.

Source code in packages/forge/src/livery/forge/_protocol.py
def add_labels(self, number: int, names: tuple[str, ...]) -> None:
    """Put the labels *names* on pull request *number*.

    Adds to the labels the pull request carries; a name already on
    it stays, so a re-run is the recovery procedure. Every name must
    already be a label of the repository: one that is not raises
    [livery.forge.ForgeError][] naming it, before anything is
    written, on every backend. Ensure the labels exist first with
    [livery.forge.Repository.configure][]. A number that names no
    pull request raises [livery.forge.ForgeError][] with status
    404.
    """
    ...

Checks

Bases: Protocol

One repository's CI: the combined verdict, runs, jobs, and logs.

GitHub and Gitea run workflows, GitLab runs pipelines. A run here is either; livery.forge.Run says how the two map.

Methods:

Name Description
status

The one CI verdict for commit sha.

runs

The repository's runs, newest first.

jobs

Every job of run run.

job_log

The raw log text of job job.

rerun

Re-run run: its failed jobs, or all of them.

cancel_run

Cancel run and its jobs.

dispatch

Trigger workflow on ref; return the run's id when the forge names it.

status

status(sha: str) -> CombinedStatus

The one CI verdict for commit sha.

Polling this is the observation model: a workflow that armed a merge watches the verdict here and observes the merge through livery.forge.PullRequests.get. A commit nothing has reported for answers none, never pending.

Source code in packages/forge/src/livery/forge/_protocol.py
def status(self, sha: str) -> CombinedStatus:
    """The one CI verdict for commit *sha*.

    Polling this is the observation model: a workflow that armed a
    merge watches the verdict here and observes the merge through
    livery.forge.PullRequests.get. A commit nothing has reported
    for answers ``none``, never ``pending``.
    """
    ...

runs

runs(*, head_sha: str = '', event: str = '', workflow: str = '', limit: int = 0) -> tuple[Run, ...]

The repository's runs, newest first.

head_sha and event filter when given. workflow names a workflow file (release.yml): GitHub and Gitea list that workflow's runs alone, and GitLab, whose pipelines carry a name only when dispatched, keeps the unnamed ones as well. With limit, the newest limit runs: the listing is read only until there are enough. Without it, the tuple is complete for the query or the call raises; a truncated listing is never returned as the answer.

Source code in packages/forge/src/livery/forge/_protocol.py
def runs(
    self,
    *,
    head_sha: str = "",
    event: str = "",
    workflow: str = "",
    limit: int = 0,
) -> tuple[Run, ...]:
    """The repository's runs, newest first.

    *head_sha* and *event* filter when given. *workflow* names a
    workflow file (``release.yml``): GitHub and Gitea list that
    workflow's runs alone, and GitLab, whose pipelines carry a name
    only when dispatched, keeps the unnamed ones as well. With
    *limit*, the newest *limit* runs: the listing is read only until
    there are enough. Without it, the tuple is complete for the
    query or the call raises; a truncated listing is never returned
    as the answer.
    """
    ...

jobs

jobs(run: int) -> tuple[Job, ...]

Every job of run run.

Source code in packages/forge/src/livery/forge/_protocol.py
def jobs(self, run: int) -> tuple[Job, ...]:
    """Every job of run *run*."""
    ...

job_log

job_log(job: int) -> str

The raw log text of job job.

The failure evidence: triage reads this, quotes it verbatim, and never reduces it to a boolean.

Source code in packages/forge/src/livery/forge/_protocol.py
def job_log(self, job: int) -> str:
    """The raw log text of job *job*.

    The failure evidence: triage reads this, quotes it verbatim,
    and never reduces it to a boolean.
    """
    ...

rerun

rerun(run: int, *, failed_only: bool = True) -> None

Re-run run: its failed jobs, or all of them.

failed_only is the cheap and usually correct choice: a green matrix leg does not need re-running to re-test a red one. Raises livery.forge.ForgeError while the run is still in progress, because there is nothing to re-run yet.

Source code in packages/forge/src/livery/forge/_protocol.py
def rerun(self, run: int, *, failed_only: bool = True) -> None:
    """Re-run *run*: its failed jobs, or all of them.

    ``failed_only`` is the cheap and usually correct choice: a
    green matrix leg does not need re-running to re-test a red
    one. Raises livery.forge.ForgeError while the run is still in
    progress, because there is nothing to re-run yet.
    """
    ...

cancel_run

cancel_run(run: int, *, force: bool = False) -> None

Cancel run and its jobs.

Required on every forge: superseded pushes cancel their stale runs, a dispatch storm is withdrawn, a starving queue is relieved by this verb instead of a wait. Raises livery.forge.ForgeError when the run is already terminal, so a caller re-running its workflow probes the run's status first.

force=True marks the jobs cancelled immediately and discards later runner reports, for a run whose runner stopped answering. It is capability-gated: a forge without force_cancel raises livery.forge.Unsupported naming the capability, and plain cancel remains available.

Source code in packages/forge/src/livery/forge/_protocol.py
def cancel_run(self, run: int, *, force: bool = False) -> None:
    """Cancel *run* and its jobs.

    Required on every forge: superseded pushes cancel their stale
    runs, a dispatch storm is withdrawn, a starving queue is
    relieved by this verb instead of a wait. Raises
    livery.forge.ForgeError when the run is already terminal, so a
    caller re-running its workflow probes the run's status first.

    ``force=True`` marks the jobs cancelled immediately and
    discards later runner reports, for a run whose runner stopped
    answering. It is capability-gated: a forge without
    ``force_cancel`` raises livery.forge.Unsupported naming the
    capability, and plain cancel remains available.
    """
    ...

dispatch

dispatch(workflow: str, *, ref: str, inputs: Mapping[str, str] | None = None) -> int | None

Trigger workflow on ref; return the run's id when the forge names it.

workflow is the workflow file name as GitHub and Gitea address one. GitLab has one pipeline definition per repository: its backend triggers the pipeline on ref and passes workflow through as a variable for the pipeline's rules to route on.

Returns:

Type Description
int | None

The id of the run the dispatch started, as

int | None

livery.forge.Checks.runs lists it, when the forge's answer

int | None

names it: GitLab answers with the pipeline it created,

int | None

GitHub and Gitea with the run's details. None when the

int | None

answer names no run, as a GitHub or Gitea server without

int | None

the run's details answers: the caller finds the run in the

int | None

listing by its event, its ref and its head commit, and two

int | None

runs dispatched together on one ref and commit cannot be

int | None

told apart there.

Source code in packages/forge/src/livery/forge/_protocol.py
def dispatch(
    self, workflow: str, *, ref: str, inputs: Mapping[str, str] | None = None
) -> int | None:
    """Trigger *workflow* on *ref*; return the run's id when the forge names it.

    *workflow* is the workflow file name as GitHub and Gitea
    address one. GitLab has one pipeline definition per
    repository: its backend triggers the pipeline on *ref* and
    passes *workflow* through as a variable for the pipeline's
    rules to route on.

    Returns:
        The id of the run the dispatch started, as
        [livery.forge.Checks.runs][] lists it, when the forge's answer
        names it: GitLab answers with the pipeline it created,
        GitHub and Gitea with the run's details. None when the
        answer names no run, as a GitHub or Gitea server without
        the run's details answers: the caller finds the run in the
        listing by its event, its ref and its head commit, and two
        runs dispatched together on one ref and commit cannot be
        told apart there.
    """
    ...

Schedules

Bases: Protocol

One repository's pipeline schedules, addressed by description.

The clock for a forge that keeps it outside the workflow file (capability pipeline_schedules). A forge whose clock is in the file raises livery.forge.Unsupported naming the capability from every method.

Methods:

Name Description
list

Every schedule of the repository, with its variables.

ensure

Make the schedule described description say ref, cron and variables.

delete

Delete the schedule described description; False when there is none.

list

list() -> tuple[Schedule, ...]

Every schedule of the repository, with its variables.

Source code in packages/forge/src/livery/forge/_protocol.py
def list(self) -> tuple[Schedule, ...]:
    """Every schedule of the repository, with its variables."""
    ...

ensure

ensure(description: str, *, ref: str, cron: str, variables: Mapping[str, str] | None = None) -> Schedule

Make the schedule described description say ref, cron and variables.

Idempotent: a schedule with that description is updated in place, none is created, and the schedule as the forge now holds it comes back. Variables named are set; variables the schedule has that variables does not name are left as they are.

Source code in packages/forge/src/livery/forge/_protocol.py
def ensure(
    self,
    description: str,
    *,
    ref: str,
    cron: str,
    variables: Mapping[str, str] | None = None,
) -> Schedule:
    """Make the schedule described *description* say *ref*, *cron* and *variables*.

    Idempotent: a schedule with that description is updated in
    place, none is created, and the schedule as the forge now
    holds it comes back. Variables named are set; variables the
    schedule has that *variables* does not name are left as
    they are.
    """
    ...

delete

delete(description: str) -> bool

Delete the schedule described description; False when there is none.

Source code in packages/forge/src/livery/forge/_protocol.py
def delete(self, description: str) -> bool:
    """Delete the schedule described *description*; False when there is none."""
    ...

Releases

Bases: Protocol

One repository's releases, addressed by tag.

Methods:

Name Description
create

Create the release for tag and return it.

get

The release for tag, or None when the tag has none.

upload_asset

Attach data to tag's release as the file name; the asset.

assets

The files attached to tag's release, in the forge's order.

download_asset

The bytes of the asset name on tag's release.

create

create(tag: str, *, name: str, body: str = '', prerelease: bool = False) -> Release

Create the release for tag and return it.

Raises livery.forge.ForgeError when tag already has a release. A re-run therefore probes with livery.forge.Releases.get first and skips the create: that pair is the idempotent whole.

Source code in packages/forge/src/livery/forge/_protocol.py
def create(
    self, tag: str, *, name: str, body: str = "", prerelease: bool = False
) -> Release:
    """Create the release for *tag* and return it.

    Raises livery.forge.ForgeError when *tag* already has a
    release. A re-run therefore probes with
    livery.forge.Releases.get first and skips the create: that
    pair is the idempotent whole.
    """
    ...

get

get(tag: str) -> Release | None

The release for tag, or None when the tag has none.

The probe that makes release creation safe to re-run.

Source code in packages/forge/src/livery/forge/_protocol.py
def get(self, tag: str) -> Release | None:
    """The release for *tag*, or None when the tag has none.

    The probe that makes release creation safe to re-run.
    """
    ...

upload_asset

upload_asset(tag: str, name: str, data: bytes, *, content_type: str = 'application/octet-stream') -> Asset

Attach data to tag's release as the file name; the asset.

Raises livery.forge.ForgeError when tag has no release, or when the release already carries an asset named name. A re-run therefore probes with livery.forge.Releases.assets first and skips the upload: that pair is the idempotent whole.

Source code in packages/forge/src/livery/forge/_protocol.py
def upload_asset(
    self,
    tag: str,
    name: str,
    data: bytes,
    *,
    content_type: str = "application/octet-stream",
) -> Asset:
    """Attach *data* to *tag*'s release as the file *name*; the asset.

    Raises livery.forge.ForgeError when *tag* has no release, or
    when the release already carries an asset named *name*. A
    re-run therefore probes with livery.forge.Releases.assets
    first and skips the upload: that pair is the idempotent whole.
    """
    ...

assets

assets(tag: str) -> tuple[Asset, ...]

The files attached to tag's release, in the forge's order.

Raises livery.forge.ForgeError when tag has no release.

Source code in packages/forge/src/livery/forge/_protocol.py
def assets(self, tag: str) -> tuple[Asset, ...]:
    """The files attached to *tag*'s release, in the forge's order.

    Raises livery.forge.ForgeError when *tag* has no release.
    """
    ...

download_asset

download_asset(tag: str, name: str) -> bytes

The bytes of the asset name on tag's release.

The forge reads its own store: a private repository needs the lane's credential, and each forge addresses the bytes its own way, so a caller never builds the download URL itself.

Raises livery.forge.ForgeError when tag has no release or the release carries no asset named name.

Source code in packages/forge/src/livery/forge/_protocol.py
def download_asset(self, tag: str, name: str) -> bytes:
    """The bytes of the asset *name* on *tag*'s release.

    The forge reads its own store: a private repository needs the
    lane's credential, and each forge addresses the bytes its own
    way, so a caller never builds the download URL itself.

    Raises livery.forge.ForgeError when *tag* has no release or
    the release carries no asset named *name*.
    """
    ...

Issues

Bases: Protocol

One repository's issues: text in both directions.

An issue's body is carried in full on create, get, list, and search, because the body is the work order in issue-driven workflows and the marker text in deduplication probes.

Methods:

Name Description
create

Open an issue and return it.

get

The issue number, body included, or None when it does not exist.

list

The repository's issues in state. Pull requests never appear.

search

The issues whose title or body contains text.

assign

Add assignee to the issue's assignees.

unassign

Remove the authenticated user from the issue's assignees.

assigned_to_me

The open issues assigned to the authenticated user.

update

Rewrite issue number's title, body, or both.

comment

Post body as a comment on issue number.

comments

The comments on issue number, oldest first, each in full.

close

Close issue number; closing a closed issue is a no-op.

reopen

Reopen issue number; reopening an open issue is a no-op.

create

create(title: str, *, body: str = '', labels: tuple[str, ...] = (), assignee: str = '') -> Issue

Open an issue and return it.

labels are label names; ensure they exist first with livery.forge.Repository.configure. A creator that must not file duplicates searches for its marker text with livery.forge.Issues.search before creating.

Source code in packages/forge/src/livery/forge/_protocol.py
def create(
    self,
    title: str,
    *,
    body: str = "",
    labels: tuple[str, ...] = (),
    assignee: str = "",
) -> Issue:
    """Open an issue and return it.

    *labels* are label names; ensure they exist first with
    livery.forge.Repository.configure. A creator that must not
    file duplicates searches for its marker text with
    livery.forge.Issues.search before creating.
    """
    ...

get

get(number: int) -> Issue | None

The issue number, body included, or None when it does not exist.

The existence probe every write to an issue runs first: the subject of a write is verified, never assumed.

Source code in packages/forge/src/livery/forge/_protocol.py
def get(self, number: int) -> Issue | None:
    """The issue *number*, body included, or None when it does not exist.

    The existence probe every write to an issue runs first: the
    subject of a write is verified, never assumed.
    """
    ...

list

list(*, state: StateFilter = 'open') -> tuple[Issue, ...]

The repository's issues in state. Pull requests never appear.

Source code in packages/forge/src/livery/forge/_protocol.py
def list(self, *, state: StateFilter = "open") -> tuple[Issue, ...]:
    """The repository's issues in *state*. Pull requests never appear."""
    ...

search

search(text: str, *, state: StateFilter = 'open', labels: tuple[str, ...] = ()) -> tuple[Issue, ...]

The issues whose title or body contains text.

labels narrows to issues carrying every named label. The deduplication probe: an unattended creator searches for its marker text and label before it files.

Source code in packages/forge/src/livery/forge/_protocol.py
def search(
    self,
    text: str,
    *,
    state: StateFilter = "open",
    labels: tuple[str, ...] = (),
) -> tuple[Issue, ...]:
    """The issues whose title or body contains *text*.

    *labels* narrows to issues carrying every named label. The
    deduplication probe: an unattended creator searches for its
    marker text and label before it files.
    """
    ...

assign

assign(number: int, assignee: str) -> None

Add assignee to the issue's assignees.

Adds rather than replaces, so a colleague's assignment survives; how many assignees an issue may carry is workspace policy, enforced by the caller, because the forges' own limits differ (GitLab's free tier carries one).

Source code in packages/forge/src/livery/forge/_protocol.py
def assign(self, number: int, assignee: str) -> None:
    """Add *assignee* to the issue's assignees.

    Adds rather than replaces, so a colleague's assignment
    survives; how many assignees an issue may carry is workspace
    policy, enforced by the caller, because the forges' own
    limits differ (GitLab's free tier carries one).
    """
    ...

unassign

unassign(number: int) -> None

Remove the authenticated user from the issue's assignees.

Only the caller's own assignment: a colleague's stays. Not being assigned is a no-op, so re-running is the recovery.

Source code in packages/forge/src/livery/forge/_protocol.py
def unassign(self, number: int) -> None:
    """Remove the authenticated user from the issue's assignees.

    Only the caller's own assignment: a colleague's stays. Not
    being assigned is a no-op, so re-running is the recovery.
    """
    ...

assigned_to_me

assigned_to_me() -> tuple[Issue, ...]

The open issues assigned to the authenticated user.

Source code in packages/forge/src/livery/forge/_protocol.py
def assigned_to_me(self) -> tuple[Issue, ...]:
    """The open issues assigned to the authenticated user."""
    ...

update

update(number: int, *, title: str = '', body: str = '') -> None

Rewrite issue number's title, body, or both.

Only the provided (non-empty) fields change; clearing a text to empty is not part of the contract. A number that names nothing raises livery.forge.ForgeError.

Source code in packages/forge/src/livery/forge/_protocol.py
def update(self, number: int, *, title: str = "", body: str = "") -> None:
    """Rewrite issue *number*'s title, body, or both.

    Only the provided (non-empty) fields change; clearing a text
    to empty is not part of the contract. A number that names
    nothing raises [livery.forge.ForgeError][].
    """
    ...

comment

comment(number: int, body: str) -> None

Post body as a comment on issue number.

Source code in packages/forge/src/livery/forge/_protocol.py
def comment(self, number: int, body: str) -> None:
    """Post *body* as a comment on issue *number*."""
    ...

comments

comments(number: int) -> tuple[Comment, ...]

The comments on issue number, oldest first, each in full.

The thread continues the work order the body opened, so it is read whole, the way the body is. Only what people wrote is a comment: a forge's own system notes are left out. Raises livery.forge.ForgeError with status 404 when the issue does not exist.

Source code in packages/forge/src/livery/forge/_protocol.py
def comments(self, number: int) -> tuple[Comment, ...]:
    """The comments on issue *number*, oldest first, each in full.

    The thread continues the work order the body opened, so it is
    read whole, the way the body is. Only what people wrote is a
    comment: a forge's own system notes are left out. Raises
    livery.forge.ForgeError with status 404 when the issue does
    not exist.
    """
    ...

close

close(number: int) -> None

Close issue number; closing a closed issue is a no-op.

Idempotent so re-running is the recovery. The reason belongs in a comment posted before the close: every forge keeps the thread, none has a first-class close reason worth abstracting.

Source code in packages/forge/src/livery/forge/_protocol.py
def close(self, number: int) -> None:
    """Close issue *number*; closing a closed issue is a no-op.

    Idempotent so re-running is the recovery. The reason belongs
    in a comment posted before the close: every forge keeps the
    thread, none has a first-class close reason worth abstracting.
    """
    ...

reopen

reopen(number: int) -> None

Reopen issue number; reopening an open issue is a no-op.

The inverse of close, for an issue a merge closed before its work was done. A missing number raises.

Source code in packages/forge/src/livery/forge/_protocol.py
def reopen(self, number: int) -> None:
    """Reopen issue *number*; reopening an open issue is a no-op.

    The inverse of `close`, for an issue a merge closed before its
    work was done. A missing number raises.
    """
    ...

Repository

Bases: Protocol

One repository on one forge.

A cheap value bound to the owner and name, obtained from livery.forge.Forge.repository. The operation groups mirror the workflow vocabulary: pr.open, checks.status, issue.search, release.get.

Methods:

Name Description
ensure_pages

Enable the forge's static-site hosting for this repository.

rate_budget

The API budget the forge last reported to this view's client.

configure

Assert the repository settings config states.

tags

Every tag name on the repository, or every one starting with prefix.

branch_exists

Whether branch exists on the repository.

protection

The protection configured for branch, or None when none is.

web_url

The repository's home page address.

pr_url

The address of pull request number.

issue_url

The address of issue number.

commit_url

The address of commit sha.

compare_url

The address comparing base to head (refs or shas).

tag_url

The address of tag's release or tag view.

delete_branch

Delete branch from the 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.

pr PullRequests

The pull request operations.

checks Checks

The CI operations.

issue Issues

The issue operations.

release Releases

The release operations.

schedule Schedules

The pipeline schedule operations (capability pipeline_schedules).

owner property

owner: str

The user, organisation, or group path that owns the repository.

name property

name: str

The repository name within the owner.

pr property

The pull request operations.

checks property

checks: Checks

The CI operations.

issue property

issue: Issues

The issue operations.

release property

release: Releases

The release operations.

schedule property

schedule: Schedules

The pipeline schedule operations (capability pipeline_schedules).

ensure_pages

ensure_pages(*, build_type: str = 'workflow') -> None

Enable the forge's static-site hosting for this repository.

Idempotent: hosting already enabled with build_type is left alone, and a different build type is moved to it. Raises livery.forge.Unsupported where the forge has no Pages API to configure (capability pages_config).

Source code in packages/forge/src/livery/forge/_protocol.py
def ensure_pages(self, *, build_type: str = "workflow") -> None:
    """Enable the forge's static-site hosting for this repository.

    Idempotent: hosting already enabled with *build_type* is left
    alone, and a different build type is moved to it. Raises
    livery.forge.Unsupported where the forge has no Pages API to
    configure (capability ``pages_config``).
    """
    ...

rate_budget

rate_budget() -> RateBudget | None

The API budget the forge last reported to this view's client.

None before any response, and from a forge that reports none. A caller that polls reads it to space its requests out before the budget is spent, which ends every other caller's work with it.

Source code in packages/forge/src/livery/forge/_protocol.py
def rate_budget(self) -> RateBudget | None:
    """The API budget the forge last reported to this view's client.

    None before any response, and from a forge that reports none. A
    caller that polls reads it to space its requests out before the
    budget is spent, which ends every other caller's work with it.
    """
    ...

configure

configure(config: RepoConfig) -> None

Assert the repository settings config states.

Idempotent drift repair: fields left None are untouched, stated fields are made true whether or not they already were. Project birth and release aftercare run the same call.

Raises livery.forge.Unsupported when a stated field needs a capability the forge declines by name: required_contexts on GitLab, min_approvals on an unlicensed GitLab instance, ci_secrets on a GitHub install without the github-secrets extra. A decline can land after other stated fields already applied, so probe supports() first when that matters.

Source code in packages/forge/src/livery/forge/_protocol.py
def configure(self, config: RepoConfig) -> None:
    """Assert the repository settings *config* states.

    Idempotent drift repair: fields left None are untouched,
    stated fields are made true whether or not they already were.
    Project birth and release aftercare run the same call.

    Raises livery.forge.Unsupported when a stated field needs a
    capability the forge declines by name: ``required_contexts``
    on GitLab, ``min_approvals`` on an unlicensed GitLab
    instance, ``ci_secrets`` on a GitHub install without the
    ``github-secrets`` extra. A decline can land after other
    stated fields already applied, so probe ``supports()`` first
    when that matters.
    """
    ...

tags

tags(prefix: str = '') -> tuple[str, ...]

Every tag name on the repository, or every one starting with prefix.

Complete or raising, like every listing: release trains probe "does this tag exist" here, and a truncated answer would turn that probe into a guess. A prefix is matched by the forge, so a package's tags cost one query however many tags others have.

Source code in packages/forge/src/livery/forge/_protocol.py
def tags(self, prefix: str = "") -> tuple[str, ...]:
    """Every tag name on the repository, or every one starting with *prefix*.

    Complete or raising, like every listing: release trains probe
    "does this tag exist" here, and a truncated answer would turn
    that probe into a guess. A *prefix* is matched by the forge, so
    a package's tags cost one query however many tags others have.
    """
    ...

branch_exists

branch_exists(branch: str) -> bool

Whether branch exists on the repository.

Source code in packages/forge/src/livery/forge/_protocol.py
def branch_exists(self, branch: str) -> bool:
    """Whether *branch* exists on the repository."""
    ...

protection

protection(branch: str) -> Protection | None

The protection configured for branch, or None when none is.

The read side of livery.forge.RepoConfig, normalised per livery.forge.Protection: a flag the forge cannot express reads as its inert value. Reading protection may need an administrating token on some forges; a refusal raises livery.forge.ForgeError for the caller to degrade on.

Source code in packages/forge/src/livery/forge/_protocol.py
def protection(self, branch: str) -> Protection | None:
    """The protection configured for *branch*, or None when none is.

    The read side of livery.forge.RepoConfig, normalised per
    livery.forge.Protection: a flag the forge cannot express reads
    as its inert value. Reading protection may need an
    administrating token on some forges; a refusal raises
    livery.forge.ForgeError for the caller to degrade on.
    """
    ...

web_url

web_url() -> str

The repository's home page address.

Every *_url method builds strings from what the backend already knows; nothing goes on the wire, and the address is not probed for existence.

Source code in packages/forge/src/livery/forge/_protocol.py
def web_url(self) -> str:
    """The repository's home page address.

    Every ``*_url`` method builds strings from what the backend
    already knows; nothing goes on the wire, and the address is
    not probed for existence.
    """
    ...

pr_url

pr_url(number: int) -> str

The address of pull request number.

Source code in packages/forge/src/livery/forge/_protocol.py
def pr_url(self, number: int) -> str:
    """The address of pull request *number*."""
    ...

issue_url

issue_url(number: int) -> str

The address of issue number.

Source code in packages/forge/src/livery/forge/_protocol.py
def issue_url(self, number: int) -> str:
    """The address of issue *number*."""
    ...

commit_url

commit_url(sha: str) -> str

The address of commit sha.

Source code in packages/forge/src/livery/forge/_protocol.py
def commit_url(self, sha: str) -> str:
    """The address of commit *sha*."""
    ...

compare_url

compare_url(base: str, head: str) -> str

The address comparing base to head (refs or shas).

Source code in packages/forge/src/livery/forge/_protocol.py
def compare_url(self, base: str, head: str) -> str:
    """The address comparing *base* to *head* (refs or shas)."""
    ...

tag_url

tag_url(tag: str) -> str

The address of tag's release or tag view.

Source code in packages/forge/src/livery/forge/_protocol.py
def tag_url(self, tag: str) -> str:
    """The address of *tag*'s release or tag view."""
    ...

delete_branch

delete_branch(branch: str) -> None

Delete branch from the repository.

Idempotent: a branch already gone is success, not an error. The abort path's cleanup; merge-path deletion is repository configuration (delete_branch_on_merge), not this call.

Source code in packages/forge/src/livery/forge/_protocol.py
def delete_branch(self, branch: str) -> None:
    """Delete *branch* from the repository.

    Idempotent: a branch already gone is success, not an error.
    The abort path's cleanup; merge-path deletion is repository
    configuration (``delete_branch_on_merge``), not this call.
    """
    ...

Forge

Bases: Protocol

One forge server: identity, capabilities, and its repositories.

Construction is a backend concern, not part of the protocol. Each backend states the server and resolves its token once, and a token belongs to exactly one host: a foreign host is never sent it.

Methods:

Name Description
whoami

The authenticated user's login name.

server_version

The server's version string.

registry_url

The root of this forge's own hosted registry of kind.

supports

Whether this forge offers capability.

repository

The view onto one repository. Cheap, no network.

members

The login names under owner, an organisation or group.

teams

The team names under owner, as the forge spells them.

codeowners

Render entries as this forge's codeowners file.

user_url

The address of login's profile page.

create_repo

Create the repository and return its view.

get_repo

The repository's settings, or None when it does not exist.

delete_repo

Delete the repository.

Attributes:

Name Type Description
token str

The credential this connection authenticates with.

token property

token: str

The credential this connection authenticates with.

Empty for a connection deliberately opened anonymously. The backend resolved it once at connect time, its own dialect variables included, so a caller needing the lane's credential asks here instead of re-deriving it.

whoami

whoami() -> str

The authenticated user's login name.

The first probe of anything unattended: a wrong-host token dies here, not mid-workflow.

Source code in packages/forge/src/livery/forge/_protocol.py
def whoami(self) -> str:
    """The authenticated user's login name.

    The first probe of anything unattended: a wrong-host token
    dies here, not mid-workflow.
    """
    ...

server_version

server_version() -> str

The server's version string.

Backends with a version floor check it here and raise livery.forge.Unsupported naming the version when the server predates an operation.

Source code in packages/forge/src/livery/forge/_protocol.py
def server_version(self) -> str:
    """The server's version string.

    Backends with a version floor check it here and raise
    livery.forge.Unsupported naming the version when the server
    predates an operation.
    """
    ...

registry_url

registry_url(kind: RegistryKind, owner: str) -> str

The root of this forge's own hosted registry of kind.

For python the returned root is the registry base whose /simple child is the read index and which itself accepts uploads (the forge-registry shape); conan answers the remote URL a conan client configures; container answers the reference prefix an image tag starts with. Raises livery.forge.Unsupported, naming the kind, where this forge hosts no such registry. The forge is the default provider, never the owner: resolution and external declarations are the caller's business.

Source code in packages/forge/src/livery/forge/_protocol.py
def registry_url(self, kind: RegistryKind, owner: str) -> str:
    """The root of this forge's own hosted registry of *kind*.

    For ``python`` the returned root is the registry base whose
    ``/simple`` child is the read index and which itself accepts
    uploads (the forge-registry shape); ``conan`` answers the
    remote URL a conan client configures; ``container`` answers
    the reference prefix an image tag starts with. Raises
    livery.forge.Unsupported, naming the kind, where this forge
    hosts no such registry. The forge is the default provider,
    never the owner: resolution and external declarations are
    the caller's business.
    """
    ...

supports

supports(capability: Capability) -> bool

Whether this forge offers capability.

The honesty valve: a caller that can degrade asks here first, and a backend never pretends. The names are the livery.forge.Capability vocabulary.

Source code in packages/forge/src/livery/forge/_protocol.py
def supports(self, capability: Capability) -> bool:
    """Whether this forge offers *capability*.

    The honesty valve: a caller that can degrade asks here first,
    and a backend never pretends. The names are the
    livery.forge.Capability vocabulary.
    """
    ...

repository

repository(owner: str, name: str) -> Repository

The view onto one repository. Cheap, no network.

Source code in packages/forge/src/livery/forge/_protocol.py
def repository(self, owner: str, name: str) -> Repository:
    """The view onto one repository. Cheap, no network."""
    ...

members

members(owner: str) -> tuple[str, ...]

The login names under owner, an organisation or group.

A personal namespace answers exactly its one login: the governance declarations validate against this listing, and a solo repository's only member is its owner.

Source code in packages/forge/src/livery/forge/_protocol.py
def members(self, owner: str) -> tuple[str, ...]:
    """The login names under *owner*, an organisation or group.

    A personal namespace answers exactly its one login: the
    governance declarations validate against this listing, and a
    solo repository's only member is its owner.
    """
    ...

teams

teams(owner: str) -> tuple[str, ...]

The team names under owner, as the forge spells them.

GitHub and Gitea answer team slugs; GitLab's teams are its subgroups and it answers group paths. A personal namespace has none and answers empty.

Source code in packages/forge/src/livery/forge/_protocol.py
def teams(self, owner: str) -> tuple[str, ...]:
    """The team names under *owner*, as the forge spells them.

    GitHub and Gitea answer team slugs; GitLab's teams are its
    subgroups and it answers group paths. A personal namespace
    has none and answers empty.
    """
    ...

codeowners

codeowners(entries: tuple[CodeownersEntry, ...]) -> Codeowners

Render entries as this forge's codeowners file.

Pure string building, nothing on the wire: the canonical location and syntax are the forge's, the declarations are neutral. What a dialect cannot express (a per-path approval count outside GitLab's sections) is approximated and named in the result's notes, never dropped silently.

Source code in packages/forge/src/livery/forge/_protocol.py
def codeowners(self, entries: tuple[CodeownersEntry, ...]) -> Codeowners:
    """Render *entries* as this forge's codeowners file.

    Pure string building, nothing on the wire: the canonical
    location and syntax are the forge's, the declarations are
    neutral. What a dialect cannot express (a per-path approval
    count outside GitLab's sections) is approximated and named
    in the result's notes, never dropped silently.
    """
    ...

user_url

user_url(login: str) -> str

The address of login's profile page.

String building from the server the backend is bound to; nothing goes on the wire and the login is not verified.

Source code in packages/forge/src/livery/forge/_protocol.py
def user_url(self, login: str) -> str:
    """The address of *login*'s profile page.

    String building from the server the backend is bound to;
    nothing goes on the wire and the login is not verified.
    """
    ...

create_repo

create_repo(owner: str, name: str, *, private: bool = True, description: str = '') -> Repository

Create the repository and return its view.

The repository is initialised with a default branch that carries no protection: the creator may push its own history over the initial commit, and protection starts when the caller configures it. Raises livery.forge.ForgeError when it already exists; ensure-exists callers probe with livery.forge.Forge.get_repo first. On GitLab, owner may be a group path.

Source code in packages/forge/src/livery/forge/_protocol.py
def create_repo(
    self,
    owner: str,
    name: str,
    *,
    private: bool = True,
    description: str = "",
) -> Repository:
    """Create the repository and return its view.

    The repository is initialised with a default branch that
    carries no protection: the creator may push its own history
    over the initial commit, and protection starts when the caller
    configures it. Raises livery.forge.ForgeError when it already
    exists; ensure-exists callers probe with
    livery.forge.Forge.get_repo first. On GitLab, *owner* may be a
    group path.
    """
    ...

get_repo

get_repo(owner: str, name: str) -> RepoInfo | None

The repository's settings, or None when it does not exist.

The probe that makes repository creation safe to re-run.

Source code in packages/forge/src/livery/forge/_protocol.py
def get_repo(self, owner: str, name: str) -> RepoInfo | None:
    """The repository's settings, or None when it does not exist.

    The probe that makes repository creation safe to re-run.
    """
    ...

delete_repo

delete_repo(owner: str, name: str) -> None

Delete the repository.

Idempotent: a repository already gone is success, not an error.

Source code in packages/forge/src/livery/forge/_protocol.py
def delete_repo(self, owner: str, name: str) -> None:
    """Delete the repository.

    Idempotent: a repository already gone is success, not an
    error.
    """
    ...

Registry

Bases: Protocol

One package index, apart from the forge.

A forge and a registry are only sometimes the same server, so "which versions of this name are published" is its own one-method interface, with a backend per ecosystem.

Methods:

Name Description
versions

The published versions of package name, oldest first.

versions

versions(name: str) -> tuple[str, ...]

The published versions of package name, oldest first.

An unpublished name answers the empty tuple; an unreachable index raises livery.forge.ForgeError. The release train's "does the index see it yet" probe.

Source code in packages/forge/src/livery/forge/_protocol.py
def versions(self, name: str) -> tuple[str, ...]:
    """The published versions of package *name*, oldest first.

    An unpublished name answers the empty tuple; an unreachable
    index raises livery.forge.ForgeError. The release train's
    "does the index see it yet" probe.
    """
    ...