PackageCommands (14 of 16)
PackageCommandsclassdataclass#
ocx_sdk._clientView sourceannouncemethod#
def announce(package: str, *, tags: Iterable[str] = (), tags_file: str | Path | None = None, tags_from_registry: bool = False, refresh: bool = False, index_repo: str | None = None, forge: Forge | None = None, transport: Transport | None = None, timeout: MaybeTimeout = UNSET, retry: MaybeRetry = UNSET) -> AnnounceReportPublish a package’s curated tag set into the index (C-061).
Re-observes the named tags on the registry, rebuilds the index entry
and opens — or updates — a pull or merge request against the index
repository. mutating=True (D5): retries are off by default. A run
that changes nothing reports status="unchanged" and commits nothing.
Needs a forge credential: OcxConfig.forge_token (or an ambient
OCX_ANNOUNCE_TOKEN), or the job token under transport="git"
inside a GitLab job. Without one ocx exits 80 before touching the
network. HostEnv.minimal() drops the whole CI identity ladder, so a
hermetic handle has to name the token in its config.
Exactly one tag source is required and ocx enforces it (exit 64):
tags replaces the curated set, the other three add to it, and they
are mutually exclusive. Nothing is checked here — clap’s usage error
is the category, and it names the rule.
ocx’s --yank/--unyank/--fork/--out are not wrapped; reach them
through invoke.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
package | str | required | The package to announce, as <namespace>/<package>. |
tags | Iterable[str] | () | Replace the curated tag set with these. A committed tag
not named here is dropped; a reserved __ocx or legacy
sha256.<hex> tag named here is dropped and reported. |
tags_file | str | Path | None | None | Add the tags listed in this file — the one
cascade_repair(announce_tags=...) wrote, typically. |
tags_from_registry | bool | False | Add every tag the registry repository currently holds. |
refresh | bool | False | Re-observe every committed tag, picking up a digest that moved, without changing which tags are curated. |
index_repo | str | None | None | The index repository, as [HOST/]NAMESPACE/PROJECT.
None takes ocx’s default, ocx-sh/index. |
forge | Forge | None | None | Which forge hosts it. Inferred for github.com and gitlab.com; required for a self-hosted host. |
transport | Transport | None | None | "api" (ocx’s default) or "git", the only way a
GitLab job token can open a merge request. |
timeout | MaybeTimeout | UNSET | Seconds per attempt. Omitted takes the config’s. |
retry | MaybeRetry | UNSET | Retry policy. Defaults to no retries. |
Returns
AnnounceReport- What reached the index: status, request URL, capability checks.
Raises
AuthError- No forge credential resolved (exit 80).
UsageError- No tag source, more than one, or a self-hosted
index_repowithoutforge(exit 64). ForgeCapabilityUnavailableError- The forge refused a job-token push (exit 86).