STLPWebsite/GIT-SYNC.md

Git Sync Plugin Configuration

This document explains how to configure and use the Grav Git Sync plugin for automatic two-way synchronization.

Overview

The Git Sync plugin automatically syncs changes between:

• Grav Admin UI (non-technical user edits)
• Git Repository (source control and backup)
• Multiple environments (development, staging, production)

Installation

via GPM (Grav Plugin Manager)

# SSH into production server
ssh user@production-server.com
cd /var/www/grav

# Install plugin via GPM
php bin/gpm install git-sync

# Enable plugin
php bin/plugin:enable git-sync

via Git (Manual)

# SSH into production server
cd /var/www/grav/user/plugins

# Clone plugin
git clone https://github.com/trilbymedia/grav-plugin-git-sync git-sync

# Enable plugin
cd /var/www/grav
php bin/plugin:enable git-sync

Configuration

Basic Configuration

Edit: /var/www/grav/user/plugins/git-sync/git-sync.yaml

enabled: true

# Git Repository Configuration
repository: 'git@knownelement.com:StartingLineProductions.com/STLPWebsite.git'

# Git Branch
branch: main

# Sync Configuration
sync:
  mode: 'auto'  # auto, manual
  remote: 'origin'
  commit_message: 'Update from Grav Admin UI'
  author_name: 'Grav Admin'
  author_email: 'admin@startinglineproductions.com'

# Auto-commit Configuration
auto_commit:
  enabled: true
  delay: 30  # Seconds after edit before committing

# Auto-pull Configuration
auto_pull:
  enabled: true
  interval: 300  # Check for remote changes every 5 minutes

# Auto-push Configuration
auto_push:
  enabled: true
  delay: 60  # Seconds after commit before pushing

# File Patterns
files:
  include:
    - 'user/pages/**/*'
    - 'user/config/**/*'
  exclude:
    - 'user/cache/**/*'
    - 'user/logs/**/*'
    - 'user/tmp/**/*'
    - 'user/backup/**/*'

# Notification
notification:
  enabled: true
  email:
    to: 'charles@startinglineproductions.com'
    subject: 'Git Sync Notification'

Environment-Specific Configuration

Development (Local Docker)

Edit: config/www/user/plugins/git-sync/git-sync.yaml

enabled: true
repository: '/home/charles/Projects/STLPWebsite'
branch: main
sync:
  mode: 'manual'  # Don't auto-sync in development
auto_commit:
  enabled: false
auto_pull:
  enabled: false
auto_push:
  enabled: false

Production

Edit: /var/www/grav/user/plugins/git-sync/git-sync.yaml

enabled: true
repository: 'git@knownelement.com:StartingLineProductions.com/STLPWebsite.git'
branch: 'main'
sync:
  mode: 'auto'  # Auto-sync all changes
auto_commit:
  enabled: true
  delay: 30
auto_pull:
  enabled: true
  interval: 300
auto_push:
  enabled: true
  delay: 60

SSH Key Configuration

For Git Sync to work, the web server (www-data user) needs SSH access to the Git repository.

Setup SSH Key for Production

# SSH into production server as root
ssh root@production-server.com

# Switch to web server user
su - www-data

# Generate SSH key
ssh-keygen -t ed25519 -C "www-data@production-server.com" -N "" -f ~/.ssh/grav_sync

# Display public key
cat ~/.ssh/grav_sync.pub

# Copy this public key to your Git repository deploy keys
# Example for GitLab: https://gitlab.com/namespace/project/-/settings/repository
# Example for GitHub: https://github.com/user/repo/settings/keys
# Example for Gitea: https://git.knownelement.com/StartingLineProductions.com/STLPWebsite/settings/keys

Test SSH Connection

# As www-data user
su - www-data

# Test SSH connection to git repository
ssh -i ~/.ssh/grav_sync -T git@git.knownelement.com

# You should see: Welcome to Gitea!
# Or similar repository server greeting

Add SSH Key to Git Repository

Add the public key as a Deploy Key to the repository:

• Title: grav-sync-production
• Key: Paste contents of ~/.ssh/grav_sync.pub
• Permissions: Read/Write (needed for both pull and push)

Usage

Automatic Mode (Production)

When configured with mode: 'auto', the plugin will:

1. Watch for changes in Admin UI
2. Auto-commit after 30 seconds of no edits
3. Auto-push to git repository after 60 seconds
4. Auto-pull every 5 minutes to check for remote changes

Workflow:

1. Non-technical user edits via Admin UI
2. Plugin detects change
3. Plugin waits 30 seconds (auto_commit.delay)
4. Plugin commits change with message: "Update from Grav Admin UI"
5. Plugin waits 60 seconds (auto_push.delay)
6. Plugin pushes to git repository
7. Changes are now in git (safe and backed up)

... Meanwhile ...

8. Technical user commits locally
9. Technical user pushes to git repository
10. Plugin detects new remote commit (every 5 minutes)
11. Plugin pulls changes automatically
12. Changes are visible in Admin UI

Manual Mode (Development)

When configured with mode: 'manual', changes must be triggered manually via Admin UI.

Manual Sync Options:

1. Admin UI Button:

   • Go to: /admin/plugins/git-sync
   • Click "Sync Now" button
   • Pull from remote
   • Push to remote

2. Git CLI (for technical users):

   cd /home/charles/Projects/STLPWebsite
   git add .
   git commit -m "feat: new equipment page"
   git push origin main
   

Conflict Resolution

Automatic Merging

If there are no conflicting changes, Git Sync will automatically merge:

Remote: Added new CNC Mill page
Local: Added new pricing table to same page

Git Sync:
  1. Pulls remote changes
  2. Merges automatically (no conflicts)
  3. Commits merge
  4. Pushes to repository

Manual Conflict Resolution

If both users edit same section of same file, Git Sync will:

1. Detect conflict
2. Notify user via email and Admin UI notification
3. Pause auto-sync until conflict is resolved
4. Show conflict in Admin UI

Resolving Conflicts:

Option 1: Via Admin UI

1. Go to: /admin/plugins/git-sync
2. See conflict notification
3. Click on conflicted file
4. Review both versions (<<<<<< HEAD and >>>>>>> origin/main)
5. Choose which changes to keep
6. Remove conflict markers
7. Click "Resolve Conflict"
8. Git Sync commits resolution and pushes

Option 2: Via SSH

# SSH into production server
ssh user@production-server.com
cd /var/www/grav

# Check git status (will show conflicts)
git status

# View conflicts
git diff --name-only --diff-filter=U

# Edit conflicted file
vim user/pages/conflict.md

# Look for conflict markers:
# <<<<<<< HEAD
# Admin UI version
# =======
# Git version
# >>>>>>> origin/main

# Manually resolve conflict (keep what you want)
# Remove conflict markers

# Add resolved file
git add user/pages/conflict.md

# Commit resolution
git commit -m "fix: resolve merge conflict in conflict.md
- Resolved by [your name]
- Kept both [specific changes]"

# Push resolution
git push origin main

# Notify Git Sync conflict is resolved
# (Auto-sync will resume)

Best Practices

Configuration

1. Different settings for dev and production:

   • Development: Manual mode, no auto-sync
   • Production: Auto mode, continuous sync

2. Reasonable delays:

   • auto_commit.delay: 30-60 seconds
   • auto_push.delay: 60-120 seconds
   • auto_pull.interval: 300-600 seconds (5-10 minutes)

3. Exclude temp files:

   • Always exclude: cache/, logs/, tmp/, backup/
   • Use files.include for what to sync
   • Use files.exclude for what to NOT sync

Communication

1. Notify before major changes:

   • Technical user: "I'm updating X structure, don't edit related files"
   • Non-technical user: "I'm updating X content, please don't touch this file"

2. Check conflicts regularly:

   • Visit /admin/plugins/git-sync daily
   • Check for conflict notifications
   • Resolve conflicts promptly

3. Review sync history:

   • Check git log periodically
   • Ensure commits are meaningful
   • Monitor for unexpected changes

Security

1. SSH Key Security:

   • Use deploy key (read/write only for this repo)
   • Don't use personal SSH key
   • Key has no passphrase (required for automation)
   • Key owned by www-data user (web server user)

2. File Permissions:

   • Ensure www-data user has write access to .git directory
   • Ensure www-data user can execute git commands
   • Proper SSH key permissions (600 for private, 644 for public)

3. Repository Access:

   • Repository should be private
   • Deploy key should have limited access
   • Monitor deploy key usage

Troubleshooting

Issue 1: Auto-sync Not Working

Symptoms: Changes made via Admin UI not committed to git

Diagnosis:

# Check plugin is enabled
ssh user@production-server.com
cd /var/www/grav
php bin/plugin:list | grep git-sync

# Check plugin configuration
cat user/plugins/git-sync/git-sync.yaml

# Check git log (should show recent commits)
git log --oneline -5

Solutions:

1. Plugin not enabled:

   php bin/plugin:enable git-sync
   

2. Wrong repository URL:

   • Check repository: in git-sync.yaml
   • Ensure SSH key can access repository

3. SSH key not working:

   # Test SSH connection
   su - www-data
   ssh -i ~/.ssh/grav_sync -T git@your-git-server.com
   

4. File permissions:

   # Fix permissions
   chown -R www-data:www-data /var/www/grav/.git
   chmod 700 /var/www/grav/.git
   

Issue 2: Changes Not Pushing to Remote

Symptoms: Commits made locally but not visible in remote repository

Diagnosis:

# Check git status
git status

# Check remote branches
git branch -r

# Check recent commits (remote)
git log origin/main --oneline -3

Solutions:

1. Network issues:

   • Check network connectivity
   • Check firewall rules
   • Verify Git server is accessible

2. Authentication issues:

   • Verify SSH key is added to repository
   • Test SSH connection
   • Check deploy key permissions

3. Remote not configured:

   git remote -v
   # Should show: origin git@server:repo.git (fetch/push)
   

Issue 3: Merge Conflicts

Symptoms: Admin UI shows conflict notification, auto-sync paused

Solutions:

1. Resolve via Admin UI:

   • Navigate to /admin/plugins/git-sync
   • Click on conflicted file
   • Edit and resolve conflict
   • Click "Resolve Conflict"

2. Resolve via SSH:

   • SSH into server
   • Resolve conflict in file
   • git add and git commit
   • git push
   • Notify Git Sync

3. Prevent conflicts:

   • Communicate with other users
   • Edit different files when possible
   • Use git status before editing

Issue 4: Files Not Being Committed

Symptoms: Some files edited in Admin UI not being committed

Diagnosis:

# Check file patterns
cat user/plugins/git-sync/git-sync.yaml | grep -A 10 "files:"

Solutions:

1. File not in include pattern:

   • Add file to files.include
   • Or use wildcard: user/pages/**/*

2. File excluded:

   • Remove from files.exclude
   • Or modify exclude pattern

3. File ignored by git:

   • Check .gitignore
   • Remove file from .gitignore if needed

Monitoring

Check Sync Status

Via Admin UI:

• Navigate to: /admin/plugins/git-sync
• View: Last sync time, last commit, last push/pull
• View: Any errors or conflicts

Via SSH:

# Check git status
cd /var/www/grav
git status

# Check recent commits
git log --oneline -10

# Check remote sync status
git log origin/main --oneline -3

# Check if auto-sync is running
ps aux | grep grav-sync

Email Notifications

Configure notifications for important events:

notification:
  enabled: true
  email:
    to: 'admin@startinglineproductions.com'
    subject: 'Git Sync Notification'
    on_commit: true
    on_push: true
    on_pull: true
    on_conflict: true
    on_error: true

Advanced Configuration

Multiple Branches

Use different branches for different purposes:

# Production
branch: 'production'

# Staging
branch: 'staging'

# Development
branch: 'dev'

Custom Commit Messages

Templates for different types of changes:

sync:
  commit_message: 'Update from Grav Admin UI'

# Or use dynamic message:
  commit_message_template: 'Update {file} from Admin UI by {user}'

Selective Sync

Only sync specific files or directories:

files:
  include:
    - 'user/pages/05.areas/**/*'  # Only sync area pages
    - 'user/config/site.yaml'      # Only sync site config
  exclude:
    - 'user/pages/04.equipment/**/*'  # Don't sync equipment pages

Comparison: Git Sync vs Manual Sync

Feature	Git Sync Plugin	Manual Sync
Automatic commits	✅ Yes	❌ No
Automatic push	✅ Yes	❌ No
Automatic pull	✅ Yes	❌ No
Conflict detection	✅ Yes	⚠️ Manual
Email notifications	✅ Yes	❌ No
Setup complexity	⚠️ Medium	✅ Simple
User intervention	⚠️ Sometimes	✅ Always
Reliable sync	✅ High	⚠️ Depends on user

Summary

Key Points:

• Git Sync plugin automates two-way synchronization
• Eliminates need for manual sync processes
• Automatically commits Admin UI changes
• Automatically pushes to git repository
• Automatically pulls remote changes
• Handles conflicts gracefully
• Requires SSH key configuration
• Different configs for dev and production

Configuration Files:

• Production: /var/www/grav/user/plugins/git-sync/git-sync.yaml
• Development: config/www/user/plugins/git-sync/git-sync.yaml

Workflow with Git Sync:

1. Non-technical user edits via Admin UI
2. Git Sync automatically commits and pushes
3. Technical user edits locally and pushes
4. Git Sync automatically pulls changes
5. Both users see each other's changes automatically

---

For more details:

• Plugin Repository: https://github.com/trilbymedia/grav-plugin-git-sync
• Official Documentation: https://github.com/trilbymedia/grav-plugin-git-sync/blob/master/README.md
• Workflow Guide: See WORKFLOW.md