Documentation
¶
Overview ¶
Package gitsync treats {apps_dir} as a git working tree, committing local changes and pulling remote changes on a poll interval or webhook trigger.
Only the following paths are tracked (via .gitignore whitelist):
**/docker-compose.yml **/.env **/simpledeploy.yml _global.yml
Conflict resolution: server (local) always wins. During a rebase, go-git's conflict resolution is limited, so we fall back to shelling out to git for the rebase+checkout-ours step. See conflict.go for details.
Index ¶
- func ValidateBranch(branch string) error
- func ValidateRemote(cfg Config) error
- func ValidateRemoteURL(remote string) error
- type CommitInfo
- type Config
- type Conflict
- type Reconciler
- type ReconcilerFunc
- type RemoteCheck
- type Status
- type Syncer
- func (g *Syncer) ApplyPending(ctx context.Context) error
- func (g *Syncer) EnqueueCommit(paths []string, reason string)
- func (g *Syncer) Start(ctx context.Context) error
- func (g *Syncer) Status() Status
- func (g *Syncer) Stop() error
- func (g *Syncer) SyncNow(ctx context.Context) error
- func (g *Syncer) WebhookHandler() http.Handler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateBranch ¶ added in v1.4.3
ValidateBranch accepts conservative branch names: letters, digits, '.', '_', '/' and '-', with no leading '-', no '..', no empty or dot-prefixed path components, and no '.lock' suffix.
func ValidateRemote ¶
ValidateRemote performs an ls-remote against cfg.Remote with the configured auth. Returns a descriptive error when the remote is unreachable, the URL is malformed, or auth is rejected. Used by config-save handlers so the user gets immediate feedback instead of silent push failures later.
func ValidateRemoteURL ¶ added in v1.4.3
ValidateRemoteURL accepts https://, http://, ssh://, git:// and file:// URLs, absolute local paths, and scp-like ssh remotes (user@host:path). It rejects git transport helpers (ext::, fd::, ...), other schemes, control characters, and any remote, user or host starting with '-' (which git or ssh could parse as an option). Error messages never echo the remote, since it may carry credentials.
Types ¶
type CommitInfo ¶
type CommitInfo struct {
SHA string // full SHA
ShortSHA string // first 7 chars
Subject string // first line of message
AuthorName string
AuthorEmail string
When time.Time
BotCommit bool // true when message contains "Source: simpledeploy-sync"
}
CommitInfo is a summary of a single commit for the status endpoint.
type Config ¶
type Config struct {
Enabled bool
Remote string // "git@github.com:owner/repo.git" or https URL
Branch string // default "main"
AppsDir string // working tree root
AuthorName string // default "SimpleDeploy"
AuthorEmail string // default "bot@simpledeploy.local"
SSHKeyPath string // path to private key for git@ / ssh:// remotes
HTTPSUsername string // optional; defaults to "git" for github tokens
HTTPSToken string // for https remotes
PollInterval time.Duration // default 60s. 0 disables polling.
WebhookSecret string // HMAC secret. Empty disables webhook endpoint.
// Behaviour toggles. All default to true via the resolver.
PollEnabled bool // false: poll loop is not started
AutoPushEnabled bool // false: pull-only; local changes are committed but never pushed
AutoApplyEnabled bool // false: fetch-only; use ApplyPending to apply
WebhookEnabled bool // false: /api/git/webhook returns 404
}
Config controls the sync worker.
Boolean toggle fields (PollEnabled, AutoPushEnabled, AutoApplyEnabled, WebhookEnabled) must be explicitly set; their zero value is false. The resolver always sets them explicitly, defaulting missing DB keys to true for backwards-compatibility with existing installs.
func ResolveConfig ¶
func ResolveConfig(st *store.Store, yamlCfg *appcfg.GitSyncConfig, appsDir, masterSecret string) (*Config, error)
ResolveConfig builds an effective gitsync.Config by merging DB rows (wins) over the YAML-parsed GitSyncConfig. Secrets stored as *_enc keys are decrypted with masterSecret. Returns a config with Enabled=false when neither source has the feature turned on.
type Reconciler ¶
Reconciler is the callback invoked after a pull applies changes.
type ReconcilerFunc ¶
ReconcilerFunc adapts a plain function to the Reconciler interface.
func (ReconcilerFunc) ReconcileAfterSync ¶
func (f ReconcilerFunc) ReconcileAfterSync(ctx context.Context, paths []string) error
type RemoteCheck ¶
type RemoteCheck struct {
OK bool `json:"ok"`
Code string `json:"code"` // ok|empty_repo|auth_failed|not_found|branch_missing|network|invalid_config|unknown
BranchFound bool `json:"branch_found"`
RefCount int `json:"ref_count"`
RawError string `json:"raw_error"`
}
RemoteCheck is the structured result of a connectivity probe.
func CheckRemote ¶
func CheckRemote(cfg Config) RemoteCheck
CheckRemote performs a single ls-remote against cfg.Remote and reports whether auth succeeded and whether cfg.Branch exists on the remote.
type Status ¶
type Status struct {
Enabled bool
Remote string
Branch string
HeadSHA string
LastSyncAt time.Time
LastSyncError string
PendingCommits int
DroppedRequests int64
RecentConflicts []Conflict
RecentCommits []CommitInfo
// Toggle state (mirrors Config fields).
PollEnabled bool
AutoPushEnabled bool
AutoApplyEnabled bool
WebhookEnabled bool
// AutoApplyEnabled=false state.
CommitsBehind int // remote commits not yet applied locally
PendingApply bool // true when CommitsBehind > 0 and AutoApplyEnabled=false
}
Status is a snapshot of the Syncer state for the UI / status endpoint.
type Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer coordinates git operations.
func New ¶
func New(cfg Config, st *store.Store, cs *configsync.Syncer, rec Reconciler) (*Syncer, error)
New validates config and constructs a Syncer. Does not touch disk or network.
func (*Syncer) ApplyPending ¶
ApplyPending runs fetchAndInspect + applyFetched regardless of AutoApplyEnabled. Intended for on-demand application of pending remote changes.
func (*Syncer) EnqueueCommit ¶
EnqueueCommit marks the working tree dirty and requests a commit, pushed when AutoPushEnabled (pull-only mode keeps it local). Non-blocking; drops if the channel is full. Coalesces naturally via buffered channel. While a pull is being imported the request is not queued; the paths are recorded as rewrites of pulled files and committed before the next rebase.
func (*Syncer) WebhookHandler ¶
WebhookHandler returns an http.Handler or nil if disabled. Returns a 404 handler when WebhookEnabled=false.