Documentation
¶
Overview ¶
Package sync implements forge accessory synchronization.
Two sync classes exist, ordered and not peers:
Git mirror — transport-level replication via git push --mirror. All refs, branches, tags, deletions, force updates. Mirrored from the authoritative local worktree.
Artifact projection — API-level for forge-native objects (releases). Runs only after git mirror succeeds for that accessory.
Core invariant: Git is the source of truth; everything else is downstream projection.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MirrorFailureReason ¶
type MirrorFailureReason string
MirrorFailureReason classifies git mirror push failures. Classification is best-effort via stderr substring matching. Fallback is always MirrorUnknown — classification must never crash.
const ( MirrorAuthFailed MirrorFailureReason = "auth_failed" MirrorProtectedRefRejected MirrorFailureReason = "protected_ref_rejected" MirrorNetworkFailed MirrorFailureReason = "network_failed" MirrorRemoteNotFound MirrorFailureReason = "remote_not_found" MirrorPushRejected MirrorFailureReason = "push_rejected" MirrorUnknown MirrorFailureReason = "unknown" )
type MirrorResult ¶
type MirrorResult struct {
AccessoryID string
Status SyncStatus
Duration time.Duration
Degraded bool // true when mirror failed — accessory is diverged
FailureReason MirrorFailureReason
Message string // sanitized human-readable message (never contains credentials)
}
MirrorResult reports the outcome of a git mirror push to one accessory.
func MirrorPush ¶
func MirrorPush(ctx context.Context, worktree string, mirror config.MirrorConfig) (*MirrorResult, error)
MirrorPush performs an authoritative git mirror push from the primary forge (origin) to a mirror forge. It clones from origin into a temp bare repo and pushes all heads + tags with force and prune.
Invariants:
- Never mutates the user's working repo (temp bare clone only)
- Credentials are injected via GIT_ASKPASS self-reexec, never in URLs or argv
- Process is killed on context cancellation
type ReleaseData ¶
type ReleaseData struct {
Tag string
Name string
Description string // markdown body
Draft bool
Prerelease bool
Assets []forge.Asset
Links []forge.ReleaseLink
}
ReleaseData holds all data needed to project a release to an accessory.
type ReleaseResult ¶
type ReleaseResult struct {
AccessoryID string
Status SyncStatus
Message string
}
ReleaseResult reports the outcome of release projection to one accessory.
func SyncRelease ¶
func SyncRelease(ctx context.Context, accessory config.MirrorConfig, data ReleaseData) *ReleaseResult
SyncRelease projects a release to an accessory forge. Tag is the identity key — if a release for this tag already exists, it is not recreated (idempotent). Assets are uploaded if missing.
Artifact sync must never mutate repository content (files, refs). Only forge-native surfaces.
type SyncStatus ¶
type SyncStatus string
SyncStatus represents the outcome of a sync operation.
const ( SyncSuccess SyncStatus = "success" SyncFailed SyncStatus = "failed" SyncSkipped SyncStatus = "skipped" )
Source Files