Design & Dev

GitHub Auto-Deploy Setup Guide

Github auto deploy torpedo bomber

In an effort to streamline development updates to a code base in a staging or production environment, we have created an auto-deploy setup guide for any GitHub (github.com) repository.

What you will need:

  • A server to host your site. Our example is a Ubuntu (Linux) server running either Apache or Nginx and PHP
  • SSH access to your server with sudo/root privileges
  • A GitHub.com account and repository

1 – On the web server

Here we install and set up Git on the server. We also create an SSH key so the server can talk to GitHub without using passwords.

Install git

sudo apt-get update
sudo apt install git

If you already had Git installed, make sure it’s a relatively new version – upgrade it to the latest if need be.

git --version

Set up Git

Next we will configure Git. In general these values don’t mean much, but best to make them descriptive.

git config --global user.name "[some user-name]"
git config --global user.email "[your github email]"

Create an SSH directory for the Apache/Nginx user

You can find out what user controls the Apache or Nginx processes by looking in their respective config files. We’re using the www-data user and group in our example.

sudo mkdir /var/www/.ssh
sudo chown -R www-data:www-data /var/www/.ssh/

Generate a deploy key for Apache/Nginx user

Next we want to generate a deploy key that we can add to the GitHub repo. We will be using the ssh-keygen command. The command below instructs the system to create an RSA key that belongs to the www-data user. You don’t need a passphrase, so be sure to leave it blank during the process of generating the key.

sudo -Hu www-data ssh-keygen -t rsa

Once generated, print out the key and copy it to your clipboard.

sudo cat /var/www/.ssh/id_rsa.pub

2 – On your origin (github.com)

Here we add the SSH key to the origin to allow your server to talk without passwords.

Add the SSH key to the repo

  1. https://github.com/[githubname]/[repo]/settings/keys
  2. Create a new key and name it appropriately
  3. Paste the deploy key you generated on the server and save

3 – On the web server

Now that we have the deploy key installed, we are ready to clone the repo on our web server.

Clone the repo

Here we clone the repo into a chmodded /var/www/[site_dir] folder. Note that we switch to the www-data user before running the git clone command. This is an important step because the deploy key we generated is owned by the www-data user and it will only work for that user, even if you are on the root.

cd /var/www

sudo chown -R www-data:www-data /var/www/[site_dir]

sudo su www-data

git clone [email protected]:[githubuser]/[gitrepo].git /var/www/[site_dir]
- or for branch -
git clone -b [branch_name] [email protected]:[githubuser]/[gitrepo].git /var/www/[site_dir]

exit

 

4 – Auto-Deployment

*** UPDATE: Please refer to my GitHub Auto-deploy Reprise article for a better solution. While the instructions below *can* work, I no longer recommend the ‘git pull’ methodology for an auto-deploy setup with Git. ***

If you’ve made it this far, you are almost ready. All the steps up to this point should have your web server properly communicating with your GitHub repo. You should be able to drill into your site directory, switch to your Apache/Nginx user (i.e. www-data), and run Git commands like you normally would. In fact, this is good practice in getting familiar with doing so in case you have to fix any conflicts, etc.

Option 1 – Cron

If the site is password protected a webhook won’t work. Or, if you don’t want to bother with a webhook (instructions below), you can set up a cronjob that will run pull commands as often as you’d like. The instructions below will switch to the Apache/Nginx user (i.e. www-data), traverse to the site directory, and run the git pull command — every minute.

*/1 * * * * su -s /bin/sh www-data -c 'cd /var/www/[site-dir] && git pull'

Option 2 – Webhook

Another option is setting up a webhook, which is a feature that GitHub allows for every repository. A webhook is simply a URL that GitHub will hit anytime an update is pushed to the origin. We can couple this functionality with a deployment script that will run Git commands to PULL from the origin and update your code base on your web server.

Create the deployment script for your site

Copy/paste the PHP code below and save it as ‘deploy.php’ in your site root. You will be adding this file to your repo, so you can do it in your local dev environment or on the live web server — as long as it gets added and is available at [yoursite].com/deploy.php

<?php
    /**
     * GIT DEPLOYMENT SCRIPT
     *
     * Used for automatically deploying websites via GitHub
     *
     */

    // array of commands
    $commands = array(
        'echo $PWD',
        'whoami',
        'git pull',
        'git status',
        'git submodule sync',
        'git submodule update',
        'git submodule status',
    );

    // exec commands
    $output = '';
    foreach($commands AS $command){
        $tmp = shell_exec($command);
        
        $output .= "<span style=\"color: #6BE234;\">\$</span><span style=\"color: #729FCF;\">{$command}\n</span><br />";
        $output .= htmlentities(trim($tmp)) . "\n<br /><br />";
    }
?>

<!DOCTYPE HTML>
<html lang="en-US">
<head>
    <meta charset="UTF-8">
    <title>GIT DEPLOYMENT SCRIPT</title>
</head>
<body style="background-color: #000000; color: #FFFFFF; font-weight: bold; padding: 0 10px;">
<div style="width:700px">
    <div style="float:left;width:350px;">
    <p style="color:white;">Git Deployment Script</p>
    <?php echo $output; ?>
    </div>
</div>
</body>
</html>

Add, commit, and push this to GitHub

git add deploy.php
git commit -m 'Adding the git deployment script'
git push

Set up service hook

Now, in your GitHub.com repo settings, we will set up the webhook which will automatically call the deploy URL, thus triggering a PULL request from the server to the origin.

  1. https://github.com/[githubname]/[repo]/settings/hooks
  2. Click Add webhook to add a service hook
  3. Enter the URL to your deployment script as the Payload URL – http://[yoursite].com/deploy.php
  4. Leave the rest of the options as default. Make sure ‘Active’ is checked on.
  5. Click Add webhook

Ready to Go

At this point, you should be all set! You and your team can make code updates and push them to the origin and they will automatically be pulled to your web server’s code base.

Some notes

  • Some servers may require slightly different instructions. Check out this resource: https://help.github.com/articles/generating-ssh-keys
  • Navigate the deployment script to trigger a pull and see the output:
    • http://[yoursite].com/deploy.php (this is useful for debugging)
    • When you push to the origin (GitHub), your site will automatically ping the above url (and pull your code)

Andy Schaff

Development Architect
Development Architect

Highly motivated developer with 14 years of experience who will take on any technology thrown at him. A proponent of well-formed and documented code, MVC technologies, page speed techniques, and high attention to detail, Andy is the full-stack implementation specialist and development architect at Portent.

Start call to action

See how Portent can help you own your piece of the web.

End call to action
0
Close Mobile Menu Button
Close search overlay