Deployment Capability¶

async def create_deployment_artifact(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    ref: str,
    version: str,
    inputs: dict[str, str] | None = None,
) -> ArtifactRun:
    """Start the build that *produces* the deployable artifact.

    The step :meth:`trigger_deployment` currently assumes has already
    happened.  ``ref`` is the committish to build from and ``version``
    the release identity the build is expected to publish under -- the
    remote build is what cuts the tag and pushes any version-bump
    commits, so neither exists yet when this returns.

    Optional and deliberately separate from
    :meth:`trigger_deployment`: the two are distinct stages with host
    handling between them, not two halves of one call.  Returns as
    soon as the build is *accepted*; the host observes completion via
    :meth:`get_artifact_run_status` (or a webhook) and only then
    proceeds to deploy.

    Capabilities whose remote has no build concept raise
    :class:`NotImplementedError`.
    """
    del ctx, credentials, ref, version, inputs
    raise NotImplementedError

async def create_release(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    tag: str,
    name: str,
    body_markdown: str,
    prerelease: bool = False,
) -> ReleaseInfo:
    """Create a release on the remote (e.g. a GitHub Release).

    Optional — paired with :meth:`create_tag`.  Capabilities without a
    release concept raise :class:`NotImplementedError`.
    """
    raise NotImplementedError

async def create_tag(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    sha: str,
    tag: str,
    message: str,
) -> RefInfo:
    """Create an annotated tag on the remote.

    Optional — only required for the Promote flow.  Capabilities that
    cannot mint tags raise :class:`NotImplementedError`; the host
    surfaces the error to the caller.
    """
    raise NotImplementedError

async def get_artifact_run_status(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    run_id: str,
) -> ArtifactRun:
    """Report a build run's status.

    The :class:`ArtifactRun` counterpart to
    :meth:`get_deployment_status`; ``run_id`` is what
    :meth:`create_deployment_artifact` returned, resolved against the
    remote's *build* endpoint rather than its deployment one.

    Optional -- paired with :meth:`create_deployment_artifact`.
    """
    del ctx, credentials, run_id
    raise NotImplementedError

async def get_check_status(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    committish: str,
) -> CheckStatus:
    """Aggregate CI check-runs status for a ref / SHA / tag.

    Optional — used by the release-train read path to surface a
    green/red dot per env's currently-deployed version.  Capabilities
    without a CI concept return ``'unknown'`` (the default).
    """
    del ctx, credentials, committish
    return 'unknown'

async def get_release(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    tag: str,
) -> RemoteRelease | None:
    """Return the remote release for ``tag``, metadata included.

    The richer counterpart to :meth:`get_release_notes`: same lookup,
    but it also carries who cut the release on the remote, its title,
    and its URL, so the host can attribute a release it only observed
    to a person instead of to the process that recorded it.

    Optional. Capabilities without a release concept, or that cannot
    resolve one for ``tag``, return ``None`` (the default); hosts fall
    back to :meth:`get_release_notes` for the body alone.
    """
    del ctx, credentials, tag
    return None

async def get_release_notes(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    tag: str,
) -> str | None:
    """Return the remote release's notes body for ``tag``.

    Optional -- lets the host enrich a ``Release`` node's notes with
    the remote release body (e.g. a GitHub release's "What's Changed"
    markdown) on paths that only know the tag, such as a webhook that
    created the release from a deployment event (which carries no
    body) or a resync whose deployment ``ref`` was a raw SHA.  This is
    the tag-keyed counterpart to the ``release_notes`` field
    :meth:`list_recent_deployments` populates from a deployment's ref.

    Best-effort: capabilities without a release concept, or that
    cannot resolve one for ``tag``, return ``None`` (the default) so
    the host never fails a write on a missing or unreadable release.
    """
    del ctx, credentials, tag
    return None

async def list_recent_deployments(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
    environments: list[str],
    limit: int = 1,
) -> list[RemoteDeployment]:
    """Return the most recent ``limit`` deployments per environment.

    Optional -- powers the deployment resync flow that backfills
    ``Release`` nodes and ``DEPLOYED_TO`` edges when webhook delivery
    has lapsed.  Capabilities that advertise the
    ``supports_deployment_sync`` hint MUST implement this; others
    raise :class:`NotImplementedError` (the host treats that as
    "skip resync").

    ``environments`` is the remote-facing list of environment names
    the host wants populated, in the project's preferred order.
    Capabilities should ignore environments their remote does not know
    about (rather than raising) so a partial resync still succeeds.
    Returned events MUST carry a stable ``external_run_id`` so the
    host can dedupe.  When a deployment targets a tagged release,
    populate ``release_notes`` with the release's notes body (distinct
    from the short ``description`` deploy note) so the host can persist
    it as the ``Release`` node's notes.
    """
    del ctx, credentials, environments, limit
    raise NotImplementedError

async def list_workflows(
    self,
    ctx: PluginContext,
    credentials: dict[str, str],
) -> list[WorkflowFile]:
    """List CI workflow files defined in the project's remote repo.

    Optional — used by the UI to populate a workflow dropdown when an
    operator configures assignment ``env_payloads``.  Capabilities
    without a workflow concept raise :class:`NotImplementedError`.
    """
    del ctx, credentials
    raise NotImplementedError