GitSync – Keep your (private) modules in sync with GitHub

[Mikel]

Hey folks,

we at frameless Media often develop across multiple devices – laptop, tablet, sometimes even from a phone with an AI coding assistant. Git is our single source of truth, but getting those changes onto a staging or production server has always been annoying. Especially on shared hosting where there's no SSH, no git, and git-based FTP via YAML configs is more hassle than it's worth.

We also frequently need to test new modules directly on shared hosting environments where the server setup differs from our local machines. Manually uploading files after every push? No thanks. So we built GitSync. 🎯

TL;DR:

✅ Link any installed module to its GitHub repo
✅ See all branches and their latest commits
✅ One-click sync – only changed files are downloaded
✅ GitHub Webhook support – auto-sync on every push
✅ Works on shared hosting – no git, no SSH, no cron
✅ Private repo support via GitHub Token

What's the difference to ProcessUpgrade?
ProcessUpgrade is great for updating published modules from the PW modules directory. But it tracks releases, not branches. During development, when you're pushing to `develop` or `feature/xyz` ten times a day, you need something different.

That's where GitSync comes in. 🚀

How it works

1. Install the module, add your GitHub Token (optional for public repos)
2. Go to GitSync > Add Module, pick any installed module from the dropdown
3. GitSync searches GitHub for matching repositories automatically
4. Link the module to a repo + branch – done

From now on, you can sync with one click. GitSync compares file hashes locally and remotely (using the same SHA1 blob hashing that git uses internally) and only downloads what actually changed. No full re-downloads, minimal API usage.

Want it fully automatic? Set up a GitHub Webhook – enter a secret in the module config, point the webhook to `https://yoursite.com/gitsync-webhook/`, and every push triggers an automatic sync. The module overview shows a ⚡ webhook badge on auto-synced modules so you always know what's wired up.

The real power: remote development with AI 📱
You're on the train, phone in hand, chatting with Claude via the Claude app. Claude writes code, commits to a feature branch on GitHub. GitSync picks up the webhook and syncs the module to your dev server. Automatically. You open the edited webpage on your phone, check the result, give feedback, iterate. The entire development loop without ever opening a laptop. 🤯

This works just as well for teams: multiple developers push to GitHub from different machines, and the staging server always reflects the latest state – no manual deploys, no SSH sessions, no FTP. We've been using a prototype internally for a few weeks now and it's become part of our daily workflow – especially the webhook auto-sync is something we don't want to miss anymore. As proof of concept we built the public release entirely as described above 😃

Technical details for the curious
The differential sync works like GIT itself: every file's content is hashed as `sha1("blob {size}\0{content}")`. GitHub's Trees API returns these hashes for the entire branch in a single request. GitSync computes the same hash locally. Matching hash = identical file = skip.

Requirements
ProcessWire >= 3.0 and PHP >= 7.4 with cURL

Module and Docs
👉 GitHub: https://github.com/frameless-at/GitSync
👉 Module Directory: https://processwire.com/modules/git-sync/

Would love to hear your thoughts, ideas, and edge cases we might not have considered!
Cheers, Mike

[Mikel]

Update: Improved "Link Module" UX

We had an internal discussion about the "Link Module" interface and optimized how the different states are handled:

Match found – The repo is resolved and ready to link. The green link opens the repository on GitHub so you can verify it's the right one before linking. This appears instantly when the module declares its GitHub URL in getModuleInfo() or has been resolved before (cached), otherwise after a quick GitHub search.

No repo found – ProModules like RepeaterMatrix have no public GitHub repo. GitSync shows a clear "No repositories found." instead of false matches.

Multiple repos – When a module exists in several repos (forks, different maintainers), you get a list to pick from.

Selected, with "change" – After picking one, a "change" link lets you switch. It only appears when there are actually alternatives.

Other improvements:

• single results are now auto-selected (no unnecessary click),
• the GitHub search uses Code Search API for exact .module.php filename matching (works even when repo name ≠ class name),
• and results are cached client-side so re-selecting a module is instant.

Cheers, Mike

[Mikel]

Update – Auto-Sync for third party modules – v0.2.0
  
Hi, folks, a new feature for the GitSync module: for public third-party modules where you can't add a webhook on the source repo, GitSync can now check for upstream updates automatically.

How it works
Every linked module has a new per-row "Auto-Sync" setting in the GitSync overview:

• off – manual sync only (default)
• notify – on the first admin page load per session, GitSync queries GitHub for the tracked branch. If a newer commit exists, a warning notice appears with a direct link to the branches view:
  
   
• auto-sync – same check, but performs the sync immediately without confirmation.

Once a remote update has been detected, an orange "update available" badge stays on the GitSync overview next to the affected module – so the info is still there after dismissing the notice.

Throttling and scope

• Checks run once per session (right after admin login), not on every page load.
• Webhook-active mappings are skipped entirely.
• GitSync itself is excluded from auto-sync – self-updates remain manual.

Why we built it
Webhooks are the cleanest path for repos you own. For public modules from other authors you don't control, you'd previously have to remember to check for updates manually. Now the module nudges you on login (or syncs straight away if you trust the upstream).

Feedback welcome,
Cheers, Mike

[matjazp]

@mikel, would you mind fixing the issue I reported? How your module compare to ProcessWireUpgrade module form Ryan? Just to let you know, I couldn't upgrade TracyDebugger. I guess to many files? I also successfuly upgraded NativeAnalytics, but the module didn't worked well, like something was missing, maybe incomplete download or something? Not sure how to debug...

[Mikel]

1 hour ago, matjazp said:

@mikel, would you mind fixing the issue I reported? 

Hi, @matjazp thanks for the report! We fixed it by removing the 3 calls. Just upgrade the module to 0.2.1
 

1 hour ago, matjazp said:

How your module compare to ProcessWireUpgrade module form Ryan? 

They solve different problems. ProcessWireUpgrade is for stable releases, GitSync is for branch-based development workflows.

ProcessWireUpgrade pulls from the official modules.processwire.com directory and compares semantic version numbers. It can upgrade the ProcessWire core itself (master or dev branch) and existing installed modules, but it cannot install new modules that aren't already present, doesn't support private repositories, doesn't support arbitrary branches per module, and uses a pull model (no webhook / no auto-sync on push). Each upgrade is a full download.

GitSync pulls from any GitHub repository — public or private (using a fine-grained Personal Access Token for the latter). It works at the branch and commit level rather than the release level, lets you switch any linked module to any branch, and detects changes by comparing git blob SHAs file-by-file, so only modified files are downloaded. It can install brand-new modules from a GitHub URL (even ones not listed in the official directory), supports private repos, and offers GitHub webhook integration for automatic sync on every push. It does not upgrade the ProcessWire core.

When to use ProcessWireUpgrade:

• Production servers that should only move to officially released versions
• Upgrading the ProcessWire core itself
• Mostly relying on modules from the official directory

When to use GitSync:

• Test/staging servers that should track a development branch (e.g. develop, feature-x) live
• Deploying your own modules from private repositories without FTP
• Installing GitHub-hosted modules that aren't (yet) in the official directory
• Auto-deploy on every git push via webhook

They can be combined: use ProcessWireUpgrade for the core, and GitSync for modules that you develop yourself or that aren´t in the PW directory.
 

1 hour ago, matjazp said:

Just to let you know, I couldn't upgrade TracyDebugger. I guess to many files?

To narrow this down — could you share:

1. Which action failed? Install from GitHub, Link Module, or Sync/Upgrade of an already-linked TracyDebugger?
2. The error or behavior you saw — blank page, timeout, rate-limit message, partial sync, etc.
3. The last lines of the gitsync log under Setup > Logs > gitsync.
4. Whether you have a GitHub Personal Access Token configured (without one you're capped at 60 API requests/hour).

The file count alone (~1,250) shouldn't be a problem for a normal upgrade — only changed files are downloaded. But it would be  a problem for a fresh Install from GitHub, where every file is fetched in its own API call. The log will tell us which case you hit.

We just tested and ran into zero problems:

• We installed Tracy via the Modules page
• added it to GitSync via the dropdown
• synced master branch

One known gotcha worth checking: TracyDebugger writes runtime files (logs, bluescreens, dumps) into its own module directory. GitSync deletes local files that don't exist in the remote repo, so a large toDelete list with permission-protected files could also cause the upgrade to fail mid-way.

Cheers,
Mike