A proposed workflow for how smaller teams can code collaboratively with git at Georgia Tech.

Defining Git

Git is an environment-agnostic version control system that allows teams or individuals to collaborate on projects in a distributed fashion. Git was created for the command line, but there are also GUI clients available.

Commits

Under the hood, git is powered by a tree of commits. Each commit tracks the difference between it and the previous commit in the tree. This saves tremendous space by storing only the changes and not the entire changed file.

Repositories

Repositories (repos) are a place where files and their histories are stored. Local repos are stored on your machine and/or the production server. The remote (origin) repo is an agreed-upon authoritative repository through which all changes flow. We use the GitHub.gatech.edu enterprise website to store our remote repos, as well as to manage their permissions and the code review process.

Branches

Central to git is the idea of branches. Each branch is just a pointer to a commit in a tree. So making a new branch is as cheap as initializing a pointer to the current commit, and updating that pointer (and only that pointer) when work is done on that branch. And because of the way git stores commits, storage for the work done on branches will be cheap too.

Branches are a way for collaborators to work together without all working on the same version of code. This allows for more advanced nonlinear workflow than a single stream of commits. It also allows for powerful administrative features such as code reviews, keeping the master (production) branch stable and testing new features without compromising that stability.

Pull requests

Pull requests are a GitHub-specific feature that encourages review of any code changes before they go live. It also gives administrators a chance to request changes or resolve conflicts before the final code is merged into the master branch.

Collaborative Workflow Overview

This workflow is based on the lightweight GitHub Flow system. This choice reflects our emphasis on less complexity for our small team, instead of focusing on a perfectly clean commit history.

In this system, all development (whether fixes or features) is done in branches and then merged back into the master/production branch when completed. Below is a sample timeline for the workflow of creating and implementing a new feature branch.

 

This workflow follows 5 rules:

1. The master branch is protected and should be kept deployable to production at all times. This is the most important rule. All code merged into master should first be thoroughly tested and reviewed. It is possible to revert the master branch, but this should be avoided whenever possible. Even if a hotfix is needed, verification of the fix should always be done in a branch. This is especially essential when our server is configured to automatically pull updates from the remote origin repo, meaning that any commit to master will quickly be made live.

2. Create separate branches off the latest master for each feature. Since branches are cheap, use one for every feature or fix. And, to ensure updated code, branch off of the current master.

3. Before every commit, pull the latest master and merge it into your local branch. One of the most challenging tasks in collaborative git is updating an existing file that needs to integrate divergent code changes from multiple developers. Merging the latest master branch into your local feature branch before every commit will largely prevent that by ensuring that any discrepancies in code are limited in scope and easily resolvable.

4. Constantly push all branches to the remote/origin repo. The remote repo isn’t just for maintaining the master branch: it can also store any other branches you are developing. This allows others to contribute to the individual branch you are working on (if you both are working on the same feature, for instance), as well as showing the current progress on each feature.

5. Use pull requests to add completed features to the master branch. Pull requests allow new features to be vetted by administrators before being added to production. Once a feature is in a mergeable state, a pull request allows discussion, review, and finally approval to get integrated into our live, master branch.

(Credit to Eli Trexler for putting together a lot of this content).

Learn how to connect a repository on github.gatech.edu to a virtual host on a server (examples given for a RHEL7 server, but similar will work IF using at least OpenSSH version 5 or higher on your server).

Make SSH Keys on Server

1. On your server, become the superuser (sudo su).
2. Create a folder in which to store SSH keys (mkdir /var/www/.ssh).
3. Create an SSH key pair on your server in that .ssh directory (ssh-keygen -b 2048 -t rsa), and name the key for the virtual host (example: /var/www/.ssh/mysite).
4. Create a config file (touch /var/www/.ssh/config) and add this code inside it:

   # mysite.gt
   Host mysite
   HostName github.gatech.edu
   PreferredAuthentications publickey
   IdentityFile /var/www/.ssh/mysite

5. Change the .ssh folder permissions (chmod 700 /var/www/.ssh).
6. Change the .ssh folder ownership for use by apache (chown -R apache:apache /var/www/.ssh).
7. Change ownership of the already-existing vhost's folder for use by apache (chown -R apache:apache /var/www/vhosts/mysite.gatech.edu).
8. Copy the contents of the public key into your Text Editor of choice (cat /var/www/.ssh/mysite.pub).

Add Deploy Key on Github

1. Create your private repo on github.gatech.edu, under the appropriate departmental Team. Do not add any files (not even a README).
2. Within your repo, click the Settings tab.
3. Choose "Deploy keys" in the left side menu, and click on "Add deploy key"
4. Give a descriptive title, like "Mysite server public key".
5. Paste the public key you copied from your server into the "Key" area.
   • If this is your initial copying of the repo from the server TO github, check "Allow write access", so that you can push to this github repo from your server.
   • If you already have the initial copy of your files pulled from the server, you need to delete the old key and make a new one that does NOT allow write access (to improve the security setup).
6. Click "Add key".

Connect your Server to Github

1. Make sure git is running (git --version).
2. Become the apache user (su -s /bin/bash - apache).
3. You probably need to symlink the .ssh directory for the apache user, so that known_hosts is saved in the correct place.
   • As the apache user, change to the home directory (cd ~)
   • Find where that home directory is located (pwd)
   • Make a symlink from your recently-created .ssh folder to apache's home directory location (ln -s /var/www/.ssh /path/to/apache/home/.ssh).

Existing Server Repository

If this vhost on your server already has a git repo initialized, follow these steps:

1. Change to your vhost's folder (cd /var/www/vhosts/mysite.cc.gatech.edu).
2. Use ssh not http to add the github repo as its origin, including the "Host" you created in the .ssh/config file as the url so that the server uses the correct ssh key to connect (git remote add origin git@mysite:My-Dept/mysite.git).
3. Push your server's repo to github (git push -u origin master).
4. Check the repo on github to make sure you see the commits from your server.

New Server Repository

If this vhost on your server does not yet have a git repo initialized, follow these steps:

1. Change to the directory above your vhost (cd /var/www/vhosts).
2. Use ssh not http to copy the repo from github to your server, including the "Host" you created in the .ssh/config file as the url so that the server uses the correct ssh key to connect (git clone git@mysite:My-Dept/mysite.git mysite.gatech.edu).
3. Change to your vhost's folder (cd /var/www/vhosts/mysite.gatech.edu).
4. Check the repo on your server to make sure you see the commits from github (git log -n 1).

Configure protected master branch on Github (Under construction section)

Since you will be connecting the repo to a Production site, you need to protect the master branch on github, so that all changes pushed to it must go through an approval process before being merged into the master/production branch.

Customize .gitignore file

For a Drupal 7 site, add these lines to the repo's .gitignore file (as they should not be version controlled):

• sites/*/files
• sites/*/private
• sites/*/settings.php

Set cron to do a git pull as the apache user (Under construction section)

Example:
0 */1 * * * cd /var/www/vhosts/mysite.gatech.edu && git pull >> /dev/null

Change File Permissions (Under construction section)

Often, the file and directory permissions on the server differ from your local development environment. You will need a cron job or automatic git-accompanying command so that, whenever it pulls updates from the remote repository, files and directories receive the correct ownership and permissions for the server.

For a Drupal 7 site, the defaults should be:

• user and group = apache:apache
• most directories = 755
• most files = 644
• not version controlled, so set it once and forget it:
  • settings.php file = 444
  • /sites/*/files = 777 (directory)
  • /sites/*/files/* = 666 (files)

Connecting to GitHub Enterprise at Georgia Tech, unlike Github.com, requires a few additional steps because GitHub Enterprise is not publicly accessible.

Please note that it is much easier to connect to GitHub Enterprise via GitHub Desktop, which natively supports enterprise installs like GitHub Enterprise at Georgia Tech.

To facilitate access to a repository in GitHub Enterprise at Georgia Tech, follow the directions below.

Setup

Derived from metroplus documentation.

1. Generate a SSH key:

   ssh-keygen -f ~/.ssh/filename-goes-here -b 4096
   

2. Copy SSH key files onto your server of choice into ~/.ssh/, making sure that your private key is chmod to 0400.
3. Add the SSH key to your GitHub Enterprise at Georgia Tech account.
4. Establish SSH fingerprint for GitHub Enterprise at Georgia Tech:
   
    ssh-keyscan github.gatech.edu >> ~/.ssh/known_hosts
    
5. Edit (or create) file config in ~/.ssh/. This file is responsible for routing the generic git@github.gatech.edu account to the defined SSH key on the server and on Github. See below for an example config file.

Sample config file

host github.gatech.edu-identifying-text-here
 Host github.gatech.edu
 IdentityFile ~/.ssh/filename-goes-here
 User git

The above configuration routes git repository URLs for Host (github.gatech.edu) to check for the SSH key file under IdentityFile with the git account (User). 

More Information

• Github Documentation on SSH