Help us shape the future of Go! Take the 2026 Go Developer Survey

gitsync

package
v1.4.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 37 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ValidateBranch added in v1.4.3

func ValidateBranch(branch string) error

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

func ValidateRemote(cfg Config) error

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

func ValidateRemoteURL(remote string) error

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: EnqueueCommit is a no-op
	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.

func (*Config) Validate added in v1.4.3

func (c *Config) Validate() error

Validate checks the remote URL and branch name without touching the network.

type Conflict

type Conflict struct {
	Path        string
	RemoteSHA   string
	ResolvedAt  time.Time
	Description string
}

Conflict records a single server-wins conflict resolution.

type Reconciler

type Reconciler interface {
	ReconcileAfterSync(ctx context.Context, changedPaths []string) error
}

Reconciler is the callback invoked after a pull applies changes.

type ReconcilerFunc

type ReconcilerFunc func(ctx context.Context, paths []string) error

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

func (g *Syncer) ApplyPending(ctx context.Context) error

ApplyPending runs fetchAndInspect + applyFetched regardless of AutoApplyEnabled. Intended for on-demand application of pending remote changes.

func (*Syncer) EnqueueCommit

func (g *Syncer) EnqueueCommit(paths []string, reason string)

EnqueueCommit marks the working tree dirty and requests a commit-and-push. Non-blocking; drops if the channel is full. Coalesces naturally via buffered channel. No-op when AutoPushEnabled=false.

func (*Syncer) Start

func (g *Syncer) Start(ctx context.Context) error

Start initializes the repo if needed and starts worker + poll loops.

func (*Syncer) Status

func (g *Syncer) Status() Status

Status returns a snapshot.

func (*Syncer) Stop

func (g *Syncer) Stop() error

Stop flushes pending commits with a short deadline and joins goroutines.

func (*Syncer) SyncNow

func (g *Syncer) SyncNow(ctx context.Context) error

SyncNow triggers an immediate fetch+pull+apply.

func (*Syncer) WebhookHandler

func (g *Syncer) WebhookHandler() http.Handler

WebhookHandler returns an http.Handler or nil if disabled. Returns a 404 handler when WebhookEnabled=false.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL