StartingLineProductions.com/STLPWebsite
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(git-sync): create comprehensive git-sync plugin guide

Browse Source 
- Document Grav Git Sync plugin for automatic two-way synchronization
- Include installation instructions via GPM and Git
- Provide complete configuration examples (basic, dev, production)
- Explain SSH key setup for production server
- Detail automatic mode workflow (production) and manual mode (development)
- Document conflict resolution (automatic and manual)
- Add best practices for configuration and communication
- Include troubleshooting guide for common issues
- Add monitoring and email notification configuration
- Provide advanced configuration (multiple branches, selective sync)
- Compare Git Sync vs manual sync approaches

Critical: Git Sync plugin automates sync process, eliminating need
for manual sync procedures. Admin UI changes are automatically
committed and pushed to git repository.

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-01-13 16:46:44 -05:00
parent c0ba97df94
commit 90bde21496
1 changed files with 619 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

619
GIT-SYNC.md Normal file
View File

@@ -0,0 +1,619 @@
# 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)
```bash
# 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)
```bash
# 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`
```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`
```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`
```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
```bash
# 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
```bash
# 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):**
```bash
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**
```bash
# 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:**
```bash
# 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:**
```bash
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:**
```bash
# Test SSH connection
su - www-data
ssh -i ~/.ssh/grav_sync -T git@your-git-server.com
```
4. **File permissions:**
```bash
# 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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:
```yaml
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:
```yaml
# Production
branch: 'production'
# Staging
branch: 'staging'
# Development
branch: 'dev'
```
### Custom Commit Messages
Templates for different types of changes:
```yaml
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:
```yaml
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