Simple Github Push To Deploy Tutorial

If you are using github as your project’s source code repository, not matter whether its open source or private, it’s good idea to have the automated deployment mechanism setup so that whenever someone from your team push to the repository, your web app get built/updated automatically to the latest changes.

There are several continuous integration system like travis, jenkins etc, which you can implement for nice automated build system. However, if your project doesn’t have that much complex build, then you can implement this automated deployment too with simple custom mechanism.

Today, I am discussing a very easy and efficient way to achieve that goal which won’t have that much complexity to have those system setup on your server. This should be an affordable way if you are just starting out/developing small/medium size apps.

I am already assuming your vps/dedicated Linux server is set up with git installation.

The 6 Steps To Achieve Our Goal:

1. Setup Your Server With a Publicly Accessible Deployment URL
2. Have A Build System Set Up On Server
3. Create A Web-hook On Github
4. Web Script/build script settings
5. Separating Production/Development Branch
6. Run Test/Debug Issues

Lets discuss the steps in detail:

1. Setup Your Server With a Publicly Accessible Deployment URL:

First requirement is to have a public URL(either IP or domain based) of the server where you need to deploy the application. So, in case its some-kind of private(password protected), you should consider making it public, or at least, provide public access to a single web hook script file that will responsible for perform other necessary operations.

2. Have A Build System Set Up On Server:

You also need to have a simple automated build system on the server for operations like pull/checkout expected revision, update dependency, update file permissions etc. For a simple build system, you can have a look at my suggestion on easily build system implementation using makefile. On the other hand, if you have proper shell permission on the server scripting language(say PHP), then you can add the commands there too as well.

3. Create A Web-hook On Github:

On your project’s settings page, go to the ‘Webhooks/Services’ section and enter the URL of the deployment script you want to have called upon every successful push/merge operations, as like below screenshot:

The ‘secret’ field is options, lets ignore it for our easy setup process.

4.Web Script/build script settings:

You will have to add the deploy script and make file paths to .gitignore file so that those aren’t considered under git repository at all. Alternatively, you can have it setup on an independent location(not under any git repo) and check/parse the payload data to detect which repository to update. It is helpful if you have multiple applications setup on same server.

These files also should have proper execution permission by the web server user(usually ‘www-data’). If you are having a make file for executing all other build operations, then the web script(here is my case, a php script) can have a very simple instruction as below:

echo shell_exec("make >application/logs/deploy.log 2>&1 </dev/null &");

Only ‘make’ command would work too, however usually, we will want to have our build output written to our log file so that we can analyze if it fails in any way. Also we are instructing the script to run in background so that on github side, we don’t face a timeout error.

5. Separating Production/Development Branch:

It’s needed to map the build server to proper git branch, if you have multiple branches deployed(one for dev, one for live etc). So, if the push is done to separate branch(say ‘dev’) than master, it should the deployed on dev server. After all testing is done, when it will be merged to master branch, it should be deployed to production server. Now, to differentiate between branches, you should use the payload data, which might be something like below:

{
  "ref": "refs/heads/master",
  "after": "480fa5cfd86d3245db9f71d852aaf2753ded8cd8",
  "before": "6290e00b02b70f016f3a6f7e6f4f129ac4062f94",
  "created": false,
  "deleted": false,
  "forced": false,
  "compare": "https://github.com/ranacseruet/codeigniterplus/compare/6290e00b02b7...480fa5cfd86d",
  "commits": [
    {
      "id": "6369e6f2ba75d2dcd5f9b221f42e2ccb642c5799",
      "distinct": true,
      "message": "* add cdn url support.\n* use cdn url on scripts/css loading.\n* favicon",
      "timestamp": "2014-08-30T23:06:11-04:00",
      "url": "https://github.com/ranacseruet/codeigniterplus/commit/6369e6f2ba75d2dcd5f9b221f42e2ccb642c5799",
      "author": {
        "name": "Md Ali Ahsan Rana",
        "email": "rana_cse_ruet@yahoo.com",
        "username": "ranacseruet"
      },
...........
}

As you can see the ‘ref’ key has value “refs/heads/master” that indicates the branch it got updated. So you can use this field for branch detection and use others as necessary.

6. Run Test/Debug Issues:

Now we can move on to test this process by pushing a simple minor change. If github side workflow is fine, you should see a ok/success status on that github webhook page as like below:

Now, you can check the log file path on the server to see how the command execution going on. In case, it didn’t go well, you can use the ‘redeliver’ button on github to send the same payload again.

Final Words:

You can have some additional measurement for public repository, like using travis, to verify your app builds fine without having any issue. You will also might want to check requesting host to prevent triggering unauthenticated triggering to deployment script.

Hope this simple tutorial on github push to deploy mechanism will help you have an automated setup on server. If you have any specific question or having any issue on any step, let me know by commenting.