Update README.md to enhance clarity and detail on deployment process and features

.gitea/workflows/syntax-check.yml

@@ -0,0 +1,44 @@
+name: Syntax Check
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - dev
+  pull_request:
+    branches:
+      - main
+      - master
+      - dev
+
+jobs:
+  syntax-check:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Install ShellCheck
+        run: apt-get update && apt-get install -y shellcheck
+      
+      - name: Check bash script syntax
+        run: |
+          echo "Checking bash scripts..."
+          shellcheck git.sh
+          shellcheck example-trigger/deploy.sh
+      
+      - name: Install PHP
+        run: apt-get install -y php-cli
+      
+      - name: Check PHP syntax
+        run: |
+          echo "Checking PHP scripts..."
+          php -l example-trigger/deploy.php
+      
+      - name: Validate YAML configuration
+        run: |
+          echo "Checking YAML files..."
+          python3 -c "import yaml; yaml.safe_load(open('bitbucket-pipelines.yml'))"
+          python3 -c "import yaml; yaml.safe_load(open('.gitea/workflows/syntax-check.yml'))"

.github/copilot-instructions.md

@@ -0,0 +1,198 @@
+# Copilot Instructions for git-incron-deploy
+
+## Project Overview
+**git-incron-deploy** is a lightweight auto-deployment system that uses `incron` (file system event monitoring) to automatically pull and deploy code from remote git repositories when triggered. It's designed for keeping development and production systems synchronized with git commits without manual intervention.
+
+## Architecture & Data Flow
+
+### Core Mechanism
+1. **Trigger Event**: External webhook (PHP/shell script) creates `git.flag` file in monitored directory
+2. **incron Detection**: `incron` watches directory for `IN_CREATE` events (new file creation)
+3. **Script Execution**: `git.sh` automatically runs on flag detection
+4. **Git Sync**: Script performs `git fetch --all` and `git reset --hard origin/<branch>` to sync code
+5. **Permissions**: Resets ownership to `www-data:www-data` for web server access
+6. **Cleanup**: Removes `git.flag` to prevent re-triggering
+
+### Configuration Files
+- **incron.d/www-deploy**: Incron watch rule defining the directory, trigger event, script path, and branch
+- **bitbucket-pipelines.yml**: CI/CD integration for automated testing (example shows deployment via calling git.sh)
+- **example-trigger/**: Sample webhook implementations (PHP and shell) that create the flag file
+
+## Key Developer Patterns
+
+### Flag-Based Triggering
+The system relies on file creation as a signal. Cannot monitor non-existent files directly, so `git.flag` must be created by external triggers. This is intentional - incron cannot watch for file creation of files that don't exist yet.
+
+### Script Parameters
+`git.sh` accepts three required parameters:
+```bash
+./git.sh <folder> <file> <branch>
+# Example: ./git.sh /var/www www-deploy master
+# $1: deployment folder path
+# $2: expected filename trigger (must be "git.flag")
+# $3: branch to deploy from remote
+```
+
+### Branch Specification
+Different branches can be deployed to different directories. Common pattern:
+- `/var/www` → production branch (often `master`)
+- `/var/www-dev` → development branch (often `dev` or `testing`)
+- Each monitored directory gets its own incron rule with branch specified
+
+### Permission Handling
+After git operations, script forces `www-data:www-data` ownership recursively. This is required because git operations may pull files owned by different users.
+
+## Integration Points
+
+### External Triggers
+Two example implementations provided:
+1. **PHP**: `touch("git.flag")` - Lightweight, suitable for webhook endpoints
+2. **Shell**: `touch git.flag` - Useful for cron jobs or manual scripts
+
+These are typically called from:
+- GitLab/Bitbucket webhooks (configured to POST to your endpoint)
+- External monitoring systems
+- Manual deployment scripts
+
+### Slack Integration
+Script calls `slackecho` function (user-implemented) for deployment notifications. The function is referenced but not defined in repo - implementer must provide their own notification wrapper.
+
+**Implementation Pattern**: Define `slackecho` as a bash function in your deployment environment or as a sourced script:
+```bash
+# Example function to add to your shell environment
+slackecho() {
+  local message="$1"
+  curl -X POST -H 'Content-type: application/json' \
+    --data "{\"text\":\"$message\"}" \
+    https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+}
+export -f slackecho
+```
+
+Or wrap deployment calls to capture output:
+```bash
+slackecho "Deploying to $1"
+# ... deployment commands ...
+slackecho "Completed"
+```
+
+The function receives human-readable messages identifying the deployment target and completion status. This allows operators to monitor deployments in real-time across multiple environments.
+
+## Deployment Workflow
+
+### Setup Checklist
+1. Clone git repo with pre-authentication configured (SSH key or git credentials)
+2. Make `git.sh` executable: `chmod +x git.sh`
+3. Install incron: `apt-get install incron` (Linux/Debian systems)
+4. Copy incron rule to `/etc/incron.d/www-deploy`, adjust paths and branch
+5. Set up external trigger (webhook or cron) to create `git.flag`
+
+### Manual Trigger (Debugging)
+```bash
+# To manually trigger deployment without webhook
+touch git.flag
+# incron will detect this and run git.sh
+```
+
+### Testing via Bitbucket Pipelines
+The pipeline runs: `chmod +x` followed by calling `git.sh` with test parameters. This validates the script works in CI environment.
+
+### Incron Rule Configuration Syntax
+Incron rules are stored in `/etc/incron.d/` with the format:
+```
+<path> <events> <script> <arguments>
+```
+
+**Production example** (from incron.d/www-deploy):
+```
+/var/www/ IN_CREATE /var/www/git.sh $@ $# master
+```
+- `/var/www/` - Directory to monitor
+- `IN_CREATE` - Only trigger on file creation events
+- `/var/www/git.sh` - Absolute path to deployment script
+- `$@` - Full path and name of the file (passed to git.sh as $2)
+- `$#` - Inode number (unused but included)
+- `master` - Branch name (passed to git.sh as $3)
+
+**Development example** (for dev branch):
+```
+/var/www-dev/ IN_CREATE /var/www-dev/git.sh $@ $# dev
+```
+
+**Key incron event types**:
+- `IN_CREATE` - File/directory created
+- `IN_DELETE` - File/directory deleted
+- `IN_MODIFY` - File modified
+- `IN_ATTRIB` - Attributes changed
+
+For this project, always use `IN_CREATE` to detect new trigger files.
+
+## Troubleshooting Common Issues
+
+### Permission Denied Errors
+**Symptom**: Deployment fails with "Permission denied" when executing git.sh
+
+**Causes & Solutions**:
+1. Script not executable: `chmod +x git.sh` on the deployment server
+2. Running user lacks permissions: Ensure incron daemon runs as root or appropriate user (check `/etc/default/incron`)
+3. Target directory not writable: Verify the directory path is writable by the incron process
+
+**Debug**: Run manually:
+```bash
+./git.sh /var/www git.flag master  # Should execute without errors
+```
+
+### Git Authentication Failures
+**Symptom**: "Permission denied (publickey)" or "Repository not found"
+
+**Causes & Solutions**:
+1. SSH keys not loaded: Incron doesn't inherit parent shell SSH keys. Configure SSH keys for the incron/www-data user:
+   ```bash
+   ssh-keygen -t rsa -f /home/incron/.ssh/id_rsa  # For incron user
+   ssh-keygen -t rsa -f /var/www/.ssh/id_rsa      # For www-data user
+   ```
+2. SSH known_hosts not populated: Pre-authenticate once manually:
+   ```bash
+   sudo -u www-data ssh -o StrictHostKeyChecking=no git@bitbucket.org
+   ```
+3. Git credentials not available: Use `.netrc` file or git credential helper configured for the deployment user
+
+**Debug**: Test git operations as the incron user:
+```bash
+cd /var/www
+sudo -u www-data git fetch --all
+```
+
+### Deployment Not Triggering
+**Symptom**: Touching git.flag manually doesn't trigger deployment
+
+**Causes & Solutions**:
+1. Incron not running: `sudo systemctl status incron` or `sudo service incron status`
+2. Incron rule syntax invalid: Test with `sudo incrontab -l` to view loaded rules
+3. Directory path incorrect: Paths in incron rules must be absolute and must end with `/` for directory watching
+4. File doesn't match trigger condition: The rule checks `$2` (filename) equals `git.flag` - ensure trigger creates exactly that filename
+
+**Debug**: Monitor incron logs:
+```bash
+tail -f /var/log/syslog | grep incron  # Debian/Ubuntu
+tail -f /var/log/messages | grep incron # RedHat/CentOS
+```
+
+### Ownership/Permission Issues After Deployment
+**Symptom**: Web server can't read deployed files after git.sh runs
+
+**Causes & Solutions**:
+1. `chown` not running as root: git.sh must execute with sufficient privileges. If running as www-data, it cannot change ownership
+2. Non-www-data deployment user: Modify the ownership line in git.sh to match your web server user (e.g., `apache:apache`, `nginx:nginx`)
+
+**Verification**:
+```bash
+ls -la /var/www/ | head -5  # Check file ownership
+```
+
+## Important Notes
+- **System Dependencies**: Requires `incron` package and file system event monitoring - Linux/Unix only
+- **Pre-authentication**: Repository must be cloned with pre-configured SSH keys or git credentials to allow unattended pulls
+- **Ownership Critical**: Web server must own deployed files for proper execution
+- **Single-Branch Limitation**: Each monitored directory watches for one specific branch (multiple directories needed for multiple branches)
+- **No Locking**: No distributed locking mechanism - concurrent triggers could cause race conditions

README.md

@@ -1,18 +1,276 @@
-# README #
+# README
 
-Set of scripts to automatically update from a remote git repository via a trigger.
+This is a set of scripts to automatically update from a remote git repository via a trigger using `incron` file system event monitoring.
 
-This trigger can be an external git repository. I used [gitlab ](https://gitlab.com/gitlab-org/gitlab-ce) to access a URL on the development and production systems, keeping them up to date with the remote git repository as commits and merges happened.
+Ideal for keeping development and production systems synchronized with git commits without manual intervention. An external webhook or cron job triggers deployment, and the system automatically pulls the latest code from a specified remote branch.
 
-### How do I get set up? ###
+## Features
 
-* clone your git repository as normal. you'll need to setup pre-authentication to enable automatic deployments.
+- **Automatic Deployments**: Monitor directories for trigger events and auto-sync code from git
-* place git.sh on the filesystem, make it executable with chmod +x
+- **Multi-Branch Support**: Deploy different branches to different directories (e.g., `master` to production, `dev` to staging)
-* install incron (apt-get install incron)
+- **Lightweight**: Simple bash script with minimal dependencies - just `incron` and bash
-* place example configuration file in /etc/incron.d/ and adjust with paths / branch
+- **Permission Handling**: Automatically sets correct ownership for web server access
-* setup a trigger. there is an example for php and shell in the examples folder. this needs to create a trigger that incron can monitor
+- **Notification Integration**: Hooks for Slack notifications on deployment start/completion
+- **CI/CD Ready**: Example integration with Bitbucket Pipelines and Gitea Actions
 
-### Who do I talk to? ###
+## How It Works
 
-* gary@hansenit.solutions
+```
-* [Hansen IT Solutions](https://hansenit.solutions)
+External Trigger (webhook/cron)
+    ↓
+Creates git.flag file
+    ↓
+incron detects IN_CREATE event
+    ↓
+Executes git.sh script
+    ↓
+git fetch --all && git reset --hard origin/<branch>
+    ↓
+Fixes file ownership for web server
+    ↓
+Sends Slack notification
+    ↓
+Cleans up git.flag
+```
+
+## Quick Start
+
+### 1. Clone Repository with Pre-Authentication
+
+Clone your git repository with SSH keys configured for unattended access:
+
+```bash
+cd /var/www
+git clone git@bitbucket.org:your-org/your-repo.git .
+```
+
+### 2. Install Dependencies
+
+```bash
+# Install incron (Linux/Debian)
+sudo apt-get install incron
+
+# Make deployment script executable
+chmod +x git.sh
+```
+
+### 3. Configure incron Rule
+
+Edit `/etc/incron.d/www-deploy` (or create it):
+
+```
+/var/www/ IN_CREATE /var/www/git.sh $@ $# master
+```
+
+Replace:
+- `/var/www/` with your deployment directory
+- `master` with your target branch (`dev`, `staging`, etc.)
+
+For multiple environments:
+
+```
+/var/www/ IN_CREATE /var/www/git.sh $@ $# master
+/var/www-dev/ IN_CREATE /var/www-dev/git.sh $@ $# dev
+/var/www-staging/ IN_CREATE /var/www-staging/git.sh $@ $# staging
+```
+
+### 4. Set Up External Trigger
+
+Create a webhook endpoint that triggers deployment. See `example-trigger/` for PHP and shell implementations:
+
+**PHP Webhook**:
+```php
+<?php
+// Endpoint that receives POST from Bitbucket/GitLab
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    // Verify webhook secret here
+    touch("git.flag");
+    echo "Deployment triggered";
+}
+```
+
+**Shell Script** (for cron jobs):
+```bash
+#!/bin/bash
+cd /var/www
+touch git.flag
+```
+
+### 5. Configure Slack Notifications (Optional)
+
+Define the `slackecho` function in your shell environment:
+
+```bash
+slackecho() {
+  local message="$1"
+  curl -X POST -H 'Content-type: application/json' \
+    --data "{\"text\":\"$message\"}" \
+    https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+}
+export -f slackecho
+```
+
+Or add to `/etc/environment` for system-wide access.
+
+## Directory Structure
+
+```
+git-incron-deploy/
+├── git.sh                      # Main deployment script
+├── bitbucket-pipelines.yml     # CI/CD example (Bitbucket)
+├── .gitea/workflows/           # Gitea Actions workflows
+├── example-trigger/
+│   ├── deploy.php             # PHP webhook example
+│   └── deploy.sh              # Bash trigger example
+├── incron.d/
+│   └── www-deploy             # incron rule template
+└── .github/
+    └── copilot-instructions.md # AI coding agent guidelines
+```
+
+## Script Parameters
+
+`git.sh` accepts three required parameters:
+
+```bash
+./git.sh <folder> <file> <branch>
+```
+
+- `<folder>`: Deployment directory path (e.g., `/var/www`)
+- `<file>`: Trigger filename (should always be `git.flag`)
+- `<branch>`: Remote branch to deploy from (e.g., `master`, `dev`)
+
+**Example**:
+```bash
+./git.sh /var/www git.flag master
+```
+
+## Manual Deployment (Debugging)
+
+To manually trigger deployment without a webhook:
+
+```bash
+cd /var/www
+touch git.flag
+# incron detects the file and runs git.sh automatically
+```
+
+Monitor the process:
+```bash
+# Check incron logs
+tail -f /var/log/syslog | grep incron
+
+# Verify file permissions
+ls -la /var/www/ | head -5
+```
+
+## Troubleshooting
+
+### Deployment Not Triggering
+
+1. **Verify incron is running**:
+   ```bash
+   sudo systemctl status incron
+   ```
+
+2. **Check incron rule syntax**:
+   ```bash
+   sudo incrontab -l
+   ```
+
+3. **Test manually**:
+   ```bash
+   cd /var/www
+   touch git.flag
+   # Should trigger immediately
+   ```
+
+4. **Monitor logs**:
+   ```bash
+   tail -f /var/log/syslog | grep incron
+   ```
+
+### Git Authentication Failures
+
+Incron runs as system user and doesn't inherit SSH keys from your shell. Configure SSH keys for the www-data user:
+
+```bash
+# Generate SSH key for www-data
+sudo -u www-data ssh-keygen -t rsa -f /var/www/.ssh/id_rsa
+
+# Add public key to Bitbucket/GitHub
+# Then test
+sudo -u www-data git fetch --all
+```
+
+### Permission Issues After Deployment
+
+Web server user must own all deployed files. `git.sh` handles this automatically by running:
+
+```bash
+chown www-data:www-data /var/www -R
+```
+
+For different web servers, modify this line:
+- Apache: `apache:apache`
+- nginx: `nginx:nginx`
+- Custom user: `youruser:youruser`
+
+## Integration Examples
+
+### Bitbucket Webhooks
+
+Configure webhook in Bitbucket repository settings:
+- **URL**: `https://your-server.com/webhook/deploy.php`
+- **Trigger**: "Push"
+
+The webhook should POST to your trigger endpoint, which creates `git.flag`.
+
+### GitLab/GitHub Webhooks
+
+Similar setup - configure push webhook to hit your trigger endpoint.
+
+### Cron-Based Deployment
+
+For scheduled deployments without webhooks:
+
+```bash
+# /etc/cron.d/deploy-cron
+0 2 * * * www-data touch /var/www/git.flag
+```
+
+## CI/CD Integration
+
+### Bitbucket Pipelines
+
+Example pipeline that validates script syntax:
+
+```yaml
+pipelines:
+  default:
+    - step:
+        script:
+          - chmod +x git.sh
+          - ./git.sh ./ git.flag master
+```
+
+### Gitea Actions
+
+Syntax checking workflow in `.gitea/workflows/syntax-check.yml`:
+- ShellCheck validation for bash scripts
+- PHP lint for PHP files
+- YAML validation for configuration files
+
+## Important Notes
+
+- **Linux/Unix Only**: Requires `incron` for file system event monitoring
+- **Pre-Authentication**: Git repository must be cloned with SSH keys or credentials configured
+- **No Concurrent Locking**: Multiple simultaneous triggers could cause race conditions
+- **Single Branch Per Directory**: Each monitored directory deploys one specific branch
+- **Root or Elevated Privileges**: `chown` requires sufficient privileges to change file ownership
+
+## Support
+
+For issues, questions, or improvements:
+- **Email**: gary@hansenit.solutions
+- **Website**: [Hansen IT Solutions](https://hansenit.solutions)