Pull Request Sync Capability¶

PullRequestSyncCapability is the contract base for a capability that ingests a project's pull-request history into ClickHouse. Bind it with a Capability(kind='pr-sync', handler=...) in the plugin's manifest.

The host addresses this capability directly (manual sync endpoints, availability checks) and permissions it independently (project:pull-requests:write). Incremental sync from inbound webhook deliveries still flows through the plugin's webhook-actions catalog.

Surfaces: api, webhook.

See Authoring Plugins for the manifest, capabilities, context, credential decryption, and error conventions shared by every plugin.

from imbi.common.plugins import (
    PluginContext,
    PullRequestSyncCapability,
)


class GitHubPullRequestSync(PullRequestSyncCapability):
    async def sync_all_history(
        self,
        *,
        ctx: PluginContext,
        credentials: dict[str, str],
    ) -> int:
        ...

    async def check_available(
        self,
        *,
        ctx: PluginContext,
        credentials: dict[str, str],
    ) -> bool:
        ...

Method contracts¶

• sync_all_history (required) — record the project's full pull-request history. Host-invoked with no webhook payload; both arguments are keyword-only. Returns the number of PRs recorded. Re-running is safe: the ClickHouse pull_requests table is ReplacingMergeTree.
• check_available (optional, default True) — whether an on-demand sync can run for ctx right now. Override to report False when the remote / repository cannot be resolved. Both arguments are keyword-only.

Hints¶

• cacheable — the host may cache reads from this capability.

API reference¶

check_available(
    *, ctx: PluginContext, credentials: dict[str, str]
) -> bool

1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803

async def check_available(
    self,
    *,
    ctx: PluginContext,
    credentials: dict[str, str],
) -> bool:
    """Whether an on-demand sync can run for ``ctx`` right now.

    Default ``True``; override to report ``False`` when the remote /
    repository can't be resolved.
    """
    del ctx, credentials
    return True

sync_all_history(
    *, ctx: PluginContext, credentials: dict[str, str]
) -> int

1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789

@abc.abstractmethod
async def sync_all_history(
    self,
    *,
    ctx: PluginContext,
    credentials: dict[str, str],
) -> int:
    """Record the project's full pull-request history.

    Host-invoked (no webhook payload). Returns the number of PRs
    recorded. Re-running is safe: the ClickHouse ``pull_requests``
    table is ``ReplacingMergeTree``.
    """