Git Sync Webhook

A lightweight, Docker-ready webhook service that automatically syncs Git repositories when GitHub webhooks are received. Perfect for keeping local repositories up-to-date with remote changes.

✨ Built with native Python libraries only - no external dependencies required!

✨ Features

• 🔄 Automatic Git Sync: Pulls latest changes on webhook events
• 🐳 Docker Ready: Full containerization with docker-compose support
• 🔐 Secure: Webhook signature verification and non-root execution
• ⚙️ Configurable: Environment variables for easy customization
• 📊 Logging: Comprehensive logging with file and console output
• 🔒 Private Repo Support: Token authentication
• 🚀 Zero Dependencies: Uses only native Python libraries
• ⚡ Post-Pull Actions: Run custom shell commands after git sync

🚀 Usage

Prerequisites

• Docker (and Docker Compose)
• Git repository (public or private)
• GitHub webhook secret

Using Docker

docker run -d \
  -p 9832:9832 \
  -v $(pwd)/repo:/app/repo:ro \
  -e WEBHOOK_SECRET=your-secret \
  -e REPO_DIR=/app/repo \
  -e BRANCH=main \
  -e POST_PULL_COMMANDS="npm install,build.sh" \
  ghcr.io/mpeciakk/git-sync-webhook:latest

Using Docker Compose

1. Create docker-compose.yml

services:
  git-sync-webhook:
    image: ghcr.io/mpeciakk/git-sync-webhook:latest
    ports:
      - "${PORT:-9832}:9832"
    environment:
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
      - REPO_DIR=${REPO_DIR:-/app/repo}
      - BRANCH=${BRANCH:-main}
      - LOG_FILE=${LOG_FILE:-/app/webhook.log}
      - VERBOSE=${VERBOSE:-false}
      - POST_PULL_COMMANDS=${POST_PULL_COMMANDS:-}
    volumes:
      - ${REPO_PATH:-./repo}:/app/repo:ro
      - ./webhook.log:/app/webhook.log
    restart: unless-stopped
     env_file: ".env"

2. Configure Environment Variables

Option A: Using docker-compose with .env file

# Create .env file
WEBHOOK_SECRET=your-github-webhook-secret-here
REPO_PATH=./repo
BRANCH=main
POST_PULL_COMMANDS=npm install,build.sh,deploy.sh

Option B: Using system environment variables

# Set environment variables in your shell
export WEBHOOK_SECRET=your-github-webhook-secret-here
export REPO_PATH=./repo
export BRANCH=main
export POST_PULL_COMMANDS="npm install,build.sh"

Option C: Passing directly to docker-compose

# Pass environment variables directly
WEBHOOK_SECRET=your-secret REPO_PATH=./repo BRANCH=main POST_PULL_COMMANDS="npm install,build.sh" docker-compose up -d

3. Clone Your Repository

git clone https://github.com/your-username/your-repo.git repo

4. Start Service

# Using docker-compose (recommended)
docker-compose up -d

Without Docker

1. Clone the Repository

git clone https://github.com/mpeciakk/git-sync-webhook.git
cd git-sync-webhook

2. Clone Your Target Repository

git clone https://github.com/your-username/your-repo.git repo

3. Run the Script

# Using environment variables
WEBHOOK_SECRET=your-secret python src/main.py

# Or set environment variables first
export WEBHOOK_SECRET=your-secret
export REPO_DIR=./repo
export BRANCH=main
export POST_PULL_COMMANDS="npm install,build.sh"
python src/main.py

# Or pass arguments directly
python src/main.py -d ./repo -b main --post-pull-command "npm install" --post-pull-command "build.sh" your-secret

📋 Configuration

Environment Variables

Variable	Required	Default	Description
WEBHOOK_SECRET	✅ Yes	-	GitHub webhook secret
REPO_DIR	❌ No	./repo	Repository path on host
BRANCH	❌ No	main	Branch to sync
PORT	❌ No	9832	Service port
LOG_FILE	❌ No	./webhook.log	Log file path
VERBOSE	❌ No	false	Enable debug logging
POST_PULL_COMMANDS	❌ No	-	Comma-separated shell commands to run after git pull

Note: Environment variables must be passed as system/shell environment variables or through docker-compose. The application does not automatically load .env files.

Post-Pull Actions

The webhook service supports running custom shell commands after a successful git pull operation. This is useful for:

• Installing dependencies (npm install, pip install -r requirements.txt)
• Building applications (npm run build, make build)
• Running tests (npm test, python -m pytest)
• Deployment scripts (deploy.sh, docker-compose up -d)

Configuration Options:

1. Environment Variable: Set POST_PULL_COMMANDS with comma-separated commands

   export POST_PULL_COMMANDS="npm install,npm run build,deploy.sh"

2. Command Line Arguments: Use --post-pull-command multiple times

   python src/main.py --post-pull-command "npm install" --post-pull-command "build.sh" your-secret

3. Docker Environment: Pass through environment variable

   docker run -e POST_PULL_COMMANDS="npm install,build.sh" ...

Important Notes:

• Commands run in the repository directory (REPO_DIR)
• Commands execute sequentially in the order specified
• If a command fails, it logs an error but continues with remaining commands
• Commands run with the same user permissions as the webhook service
• Use absolute paths for external scripts if needed

GitHub Webhook Setup

1. Go to your GitHub repository → Settings → Webhooks
2. Click Add webhook
3. Set Payload URL: http://your-server:9832/
4. Set Content type: application/json
5. Set Secret: Your webhook secret
6. Select Just the push event
7. Click Add webhook

🔐 Private Repository Support

Personal Access Token

# Create token on GitHub (Settings → Developer settings → Personal access tokens)
# Generate new token with 'repo' scope

# Update repository URL with token
git remote set-url origin https://username:token@github.com/username/repo.git

📊 Monitoring

Logs

# View logs
docker-compose logs -f

# Or from log file
tail -f webhook.log

🏗️ Development

Local Development

# Clone the repository for development
git clone https://github.com/mpeciakk/git-sync-webhook.git
cd git-sync-webhook

# Run locally with environment variables
WEBHOOK_SECRET=your-secret python src/main.py

# Or set environment variables first
export WEBHOOK_SECRET=your-secret
python src/main.py

Building Docker Image

# Clone the repository
git clone https://github.com/mpeciakk/git-sync-webhook.git
cd git-sync-webhook

# Build image
docker build -t git-sync-webhook .

# Run container with environment variables
docker run -p 9832:9832 -e WEBHOOK_SECRET=secret git-sync-webhook

🔧 Troubleshooting

Common Issues

Webhook not receiving events:

• Verify webhook URL is accessible
• Check webhook secret matches
• Ensure repository has push events

Git operations failing:

• Check repository permissions
• Verify token setup for private repos
• Ensure repository is properly cloned

Environment variables not working:

• Ensure variables are set in your shell or passed to docker-compose
• Check that variable names match exactly (case-sensitive)
• Verify docker-compose is loading .env file correctly

Permission errors:

# Fix repository permissions
chmod -R 755 ./repo
chown -R $(id -u):$(id -g) ./repo

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the Git community