Functionality on Porch Documentation

Sync Behavior

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Repository controller uses two types of sync operations to keep repositories up-to-date:

Health checks: Lightweight connectivity validation that runs frequently to detect failures quickly
Full syncs: Complete repository synchronization that runs less often to fetch content and discover packages

The controller intelligently decides which operation to perform based on repository state and configured scheduling.

Sync Operations

Health Check

Health checks perform quick connectivity validation without fetching repository contents. They execute synchronously in the reconcile loop, validating only that the repository is reachable without the overhead of git operations.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

Overview

When repository operations fail, the controller uses intelligent retry logic based on error type. Different errors require different retry strategies - transient network issues retry quickly, while authentication problems that need manual intervention retry less frequently to avoid wasting resources.

For how errors affect sync scheduling behavior, see Sync Behavior During Errors.

Error-Specific Retry Intervals

The controller analyzes error messages to determine appropriate retry timing:

Error Type	Retry Interval	Error Patterns	Rationale
Network Issues	30 seconds	“no such host”, “connection refused”	Often transient, retry quickly
Authentication	10 minutes	“authentication required”, “permission denied”	Needs manual fix, avoid spam
Git Repo/Branch	2 minutes	“not found”, “invalid”, “branch”	May be transient (repo creation)
Timeouts	1 minute	“timeout”, “deadline exceeded”	Network congestion, moderate retry
TLS/SSL Issues	5 minutes	“certificate”, “tls”, “ssl”	Configuration issues, less frequent
Rate Limiting	5 minutes	“rate limit”, “too many requests”	Need to back off from API
Default	30 seconds	All other errors	Configurable fallback

Recovery Behavior

When a repository enters an error state, the controller adjusts its behavior to focus on recovery:

Status Management

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Repository controller maintains detailed status information to track sync operations, detect changes, and provide observability. The status includes both standard Kubernetes conditions and custom fields specific to repository synchronization.

Status Fields

Repository Information

The packageCount field shows how many package revisions were discovered during the last sync.

Git Commit Tracking

For git repositories, the gitCommitHash field contains the commit hash of the configured branch, enabling GitOps workflows to track which version is currently synced.