Skip to content

API reference

Models

PipelineResult

Bases: BaseModel

The state of a single pipeline run, independent of provider.

Together, provider and id identify a pipeline run. Repositories use them to detect status changes, so a provider must return the same id for a pipeline run on every poll.

Attributes:

Name Type Description
id str

The pipeline run's ID, unique within its provider.
provider str

A short name for the provider, such as github.
repo str

The repository the pipeline run belongs to, such as owner/repo.
branch str

The branch the pipeline run was triggered on.
commit_sha str

The full SHA of the commit being built.
status PipelineStatus

The pipeline run's current status.
url str

A link to the pipeline run in the provider's web interface.
created_at datetime

When the pipeline run was created.
started_at datetime | None

When the pipeline run started, or None if it has not started.
finished_at datetime | None

When the pipeline run finished, or None if it has not finished.
raw dict[str, Any]

The provider's original response for the pipeline run.

PipelineStatus

Bases: StrEnum

The status of a pipeline run.

Attributes:

Name Type Description
PENDING

Queued or waiting to start.
RUNNING

In progress.
SUCCESS

Finished successfully.
FAILURE

Failed, including timeouts and startup failures.
CANCELLED

Cancelled before finishing.
SKIPPED

Skipped without running.
UNKNOWN

A status that does not map to any of the values above.

Plugin protocols

ProviderPlugin

Bases: Plugin, Protocol

Fetches pipeline runs from a CI/CD service.

Register providers in the pipe-ping.providers entry point group.

poll async 

poll() -> list[PipelineResult]

Return the current state of recent pipeline runs.

RepositoryPlugin

Bases: Plugin, Protocol

Stores pipeline runs and decides which changes to report.

Register a repository in the pipe-ping.repository entry point group.

save async 

save(results: list[PipelineResult]) -> list[PipelineResult]

Store results and return the ones to notify about.

NotifierPlugin

Bases: Plugin, Protocol

Reports pipeline run changes to the user.

Register notifiers in the pipe-ping.notifiers entry point group.

notify async 

notify(results: list[PipelineResult]) -> None

Report results, the pipeline runs returned by the repository.

Plugin

Bases: Protocol

Optional lifecycle methods for plugins.

setup and teardown are called only when defined, so plugins may omit them.

setup async 

setup() -> None

Prepare the plugin.

Called once at startup, with a 10-second timeout. Raise PluginUnavailableError if the plugin cannot run.

teardown async 

teardown() -> None

Release the plugin's resources.

Called once at shutdown, with a 10-second timeout.

Errors

PluginUnavailableError

Bases: PipePingPluginError, RuntimeError

Raised from setup when a plugin is not configured or cannot run.