Skip to content

Blossom and relays ​

Development preview

This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.

Choose services for the traffic ngit-ci will actually send, not just because they already host the repository. Repository hosting, CI coordination, artifact storage and binary-cache discovery have different requirements. They may share an operator or hostname, but acceptance by one service does not qualify another.

Blossom storage ​

Check each selected upload destination and its reverse proxy:

  • Protocol and identities. Support signed Blossom uploads and content-addressed reads. Permit the provider's upload identity, any separate environment-manifest identity, and the cache publisher when external cache storage is enabled. Confirm that the returned URLs are reachable from consuming guests as well as the publisher. A successful upload or existence check alone does not establish the required retention policy.
  • Blob sizes and quotas. Set request-body limits for the largest actual blob, including a packaged archive containing multiple logical artifact files. A provider's 1 GiB per-file input default and 2 GiB aggregate input default are consumer budgets, not a storage-server contract. Account separately for upload limits, total stored bytes, concurrent jobs, replicas and temporary staging. Binary-cache exports have their own limits and can be larger than job artifacts.
  • Timeouts and throughput. Allow enough time at realistic upload speeds in both storage/proxy settings and the provider's --blossom-timeout-secs. The latter covers an entire attempt; publication has a separate bounded budget. See the publication timeout guidance in publication deadlines.
  • Rate limits. Check request and byte quotas by identity and source IP, including bursts of small manifests, artifacts and cache objects. Providers sharing an egress address may share a quota. Test throttling and recovery; retries do not remove deadlines or guarantee eventual publication.
  • Retention. Keep artifacts through dependent jobs and the intended retry window; choose a separate policy for release assets and historical logs. Preserve current and historical environment manifests using the configured metadata identity. Verify whether re-uploading renews retention, establishes ownership only, or has no effect on expiry. Cache retention must preserve the referenced objects, not merely the catalog root.

Qualify services with a representative signed upload, descriptor/hash check and readback from the consumer network. Include a near-limit blob and a realistic burst, using a dedicated test identity and the operator's agreed limits. Repeat qualification after storage or proxy policy changes. Do not infer a supported maximum from one small successful upload.

The advertised provider environment describes enforced input limits at /configuration/artifacts/max-input-file-bytes and /configuration/artifacts/max-input-total-bytes. It currently makes no claim about external upload capacity. A future upload-capacity claim must reflect the configured destinations and replication policy, with evidence behind it.

Repository retention and standalone providers ​

ngit-ci publishes logs and artifacts to configured Blossom destinations, then publishes their references in signed CI events. One successful destination is sufficient; repository-host replication does not gate job completion.

A Grasp host with blob retention enabled can retain referenced CI blobs under its repository policy, including fetching them from another Blossom server. This is opt-in hosting behavior, not an ngit-ci guarantee. Confirm that the repository is selected for synchronization, its announcement lists that host, and the host accepts the referencing CI events. Its retention classes, size limits and storage budgets can still refuse or expire blobs. See ngit-grasp's docs/how-to/retain-repository-blobs.md for hosting setup and repository selection.

The initial upload destination must keep blobs available long enough for the repository host to discover and retain them. Verify retention at that host; relay acceptance, a successful upload and the presence of a repository a tag alone do not prove a durable copy exists. Preserve the signed results alongside blobs when archiving CI history.

Without a participating repository host, arrange retention directly with the upload destination. Cover dependent jobs, retries, historical log access and release downloads as appropriate. Do not rely on an unclaimed-upload grace period or assume another upload resets it. ngit-ci does not renew leases or manage a repository's archival lifecycle, and adding destinations does not establish a retention policy.

Environment manifests need separate treatment: provider advertisements are not repository-scoped results. Keep current and historical manifests available using the dedicated manifest upload identity and the storage server's retention exemption or equivalent policy. Exempting that identity need not retain every log and artifact uploaded by the provider.

Nostr relays ​

Verify both publication acceptance and subscription/readback for the kinds and identities required by each role:

TrafficRequired coverage
Repository discovery and collaborationThe NIP-34 events used by the repository and its membership policy.
CI coordination and resultsThe applicable NIP-C1 event kinds, including advertisements, allocations, progress, results and control events. Test ephemeral secret-update delivery separately when enabled.
Narwal-compatible cache discoveryDefault roots: 17091; named roots: 37091 when consumed; optional trust-list extension: 30078, with the application tags described in the cache protocol.

Do not assume a GRASP repository relay accepts cache-discovery events. A repository-only kind allowlist can reject the Narwal kinds even while Git and CI result publication work. Select an additional relay accepting those events for cache discovery, or arrange an explicit policy change with the relay operator. Likewise, provider advertisements have no repository a tag and may be rejected by repository-only policies. Follow the provider relay configuration for coordinator index relays and provider inboxes; cache discovery uses its own configured relays.

Check event-size and tag-count limits, permitted authors and authentication policy, publication rate limits, concurrent subscriptions, filter limits and connection quotas. Include reconnect bursts and multiple providers behind one IP. Replacement and expiry handling must preserve the intended event semantics; acceptance of a result does not prove an advertisement remains discoverable.

Use signed, role-appropriate test events and verify them through the same filters a real consumer uses. Check relay rejection messages and service logs. A connected WebSocket or an accepted unrelated event is insufficient evidence. Keep at least one compatible shared route between publishers and subscribers; adding several relays that all reject a required kind does not provide redundancy.