This is a lightweight utility script that synchronizes the local file system with updates from a GitHub project.
Very Important Note:
This port of BitBucket Sync for GitHub is very much in an alpha stage - it barely works and is probably extremely buggy. Use at your own risk. Updates likely to come soon though.
This script keeps your website in sync with the updates made on a GitHub project.
It is intended to be used on a web-server which is reachable from the internet and which can accept POST requests coming from GitHub servers. It works by getting all the updates from a GitHub project and applying them to a local copy of the project files.
For example, supposing you have a website which is deployed on a shared-hosting server, and the source code is stored in a private repository in GitHub. This script allows you to automatically update the deployed website each time you push changes to the GitHub project. This way, you don't have to manually copy any file from your working directory to the hosting server.
Github Deploy will synchronize only the files which have been modified, thus reducing the network traffic and deploy times.
This script requires PHP 5.3+ with cURL and Zip extensions enabled. It can be used with most shared web-hosting providers offering PHP support.
- Get the source code for this script from GitHub, either using Git, or by downloading directly.
- Copy the source files to your web-server in a location which is accessible from the internet (usually
config.phpand adjust it with information related to your environment and GitHub projects that you want to keep in sync (see Configuration section).
- Make sure all folders involved in the sync process are write-accessible (see
config.phpfor details). The most important of all is your
commitsfolder. You can test if this folder is writable by accessing the
testparameter in your browser (i.e.
- Perform an initial import of each project, through which the project files are copied to the web-server file-system (see Operation section below).
- Configure the GitHub projects to send commit information to your web server through the webhook. The hook must point to the
index.phpscript (do this for each repository that needs to be synchronized!). See more information on how to create a webhook in GitHub. POST URL should be, for example,
content typeshould be
- Start pushing commits to your GitHub projects and see if the changes are reflected on your web server.
This script has two complementary modes of operation detailed below.
1. Full synchronization
The script runs in this mode when it is accessed through the web-server and has the
setup GET parameter specified in the URL (
index.php?setup=my-project-name). In this mode, the script will get the full repository from GitHub and deploy it locally. This is achieved through getting a zip archive of the project, extracting it locally and copying its contents over to the project location specified in the configuration file.
This operation mode does not necessarily need a webhook to be defined in GitHub for the project and is generally suited for initial set-up of projects that will be kept in sync with this script.
Steps on how to get a project set up using full synchronization
If your repository is called my-project-name, you need to define it in the
config.phpfile and to specify, at least, the repo owner's username and a valid location, accessible for writing by the web server process. Optionally you can state the branch from which the deployment will be performed. The default deployment branch is 'deploy'.
After this step, simply access the script
index.phpwith the parameter
http://mysite.ext/github-deploy/index.php?setup=my-project-name). It is advisable to have verbose mode enabled in the configuration file, to see exactly what is happening.
Full synchronization mode also supports cleaning up the destination folder before attempting to import the zip archive. This can be done by specifying the
cleanURL parameter (i.e.
http://mysite.ext/github-deploy/index.php?setup=my-project-name&key=x&clean=1). When this parameter is present, the contents of the project location folder (specified in the configuration file) will be deleted before performing the actual import. In order to enhance security, when cleaning is requested (through the
cleanparameter) , the
keyparameter must also be specified, with the correct value of deploy authorization code (defined in
Once the import is complete, you can go on and setup the webhook in GitHub and start pushing changes to your project.
2. Commit synchronization
This is the default mode which is used when the
index.php script is accessed with no parameters in the URL. To work in this mode, the script needs to read the commit information received from GitHub, so a webhook must be configured before changes can be automatically synchronized. In this mode, the script updates only the files which have been modified in a commit. If a file is changed by multiple commits it will be deployed only once, with the latest content, thus reducing network traffic. The entire sync process is described below.
The process flow of commit synchronization
You make one or more commits and push to GitHub.
GitHub receives the changes and checks for any webhooks configured for the project. Since there is a webhook defined (see Installation section above), it makes a HTTP request (POST) to
index.phpscript. This request contains information about the commits that were pushed (which files have been added, updated or deleted, what branches were affected, etc).
index.phpscript records the request from GitHub in a file stored locally in
commitsfolder. This file will then be read when performing the actual sync. Storing data in a local file allows retrying the synchronization in case of failure.
This script performs the actual synchronization by reading the local file with commit meta-data and requesting from GitHub the content of files which have been changed. It will then update the local project files, one by one. After all files are updated, the meta-data file from
commitsfolder is deleted to prevent synchronizing the same changes again.
If synchronization fails, the commit files (containing the commit meta-data) are not deleted, but preserved for later processing. They can be processed again by specifying the
retryGET parameter when invoking
Note: since files are updated one by one, there is a risk of having the website in an inconsistent state until all files are updated. It is recommended to trigger the actual synchronization (step 4) only when there is a low activity on the website.
Important: if there are a lot of files added/changed/deleted in a commit and deployment is found to be incomplete afterwards, it is recommended to trigger a full synchronization to fix this.
Firstly the script needs to have access to your GitHub project files through the GitHub API. If your project is private, you need to provide the user name and password of a GitHub account with read access to the repository.
Then the script needs to know where to put the files locally once they are fetched from the GitHub servers. The branch of the repository to deploy and a few other items can also be configured.
Optionally, the scripts can be configured to require authorization in order to operate. Different authorization codes can be defined for the gateway script (which accepts commit information from GitHub) and for the deploy script (which triggers the synchronization). The key must be passed through the
key URL parameter when accessing the scripts. i.e.
index.php?key=predefined-gw-key. Note that the GitHub webhook must be updated with the correct URL in this case.
All of this information can be provided in the
config.php file (initially included in the distribution as
config.sample.php). Detailed descriptions of all configuration items is contained as comments in the file.
Important! Make sure all folders specified in the
config.php have write permission for the user under which the web-server process runs. This is mandatory in order for the script to be able to store commit meta-data files locally.
v0.3.0 added a password protected admin page (admin.php) where you can view the logs. The password is set in the config.php file. If password is blank or not set, the page will not be acessible.
- Admin page added for viewing logs
- index.php now is sole entry point
- Deploy and gateway classes implemented
- Bug fixes
- Various updates
- Config class implemented
- Bug fixes
- Initial release
- Based on BitBucket Sync v2.2.3 (c) Alex Lixandru (https://bitbucket.org/alixandru/bitbucket-sync)
This code has not been extensively tested on highly active, large GitHub projects. You should perform your own tests before using this on a live (production) environment for projects with a high number of updates.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
#Many many thanks:
To Alex Lixandru, who's BitBucket Sync program this is heavily based on. The modifications I have made to port it to GitHub are very minor and I probably couldn't have come up with something like this myself.