top
(README.md)
## Jack the Shipper

Shipper is a continuous deployment tool that leverages GitHub's [Deployments API](https://developer.github.com/v3/repos/deployments/) to allow secure asynchronous deployments.

### How does it work?

A shipper daemon polls the Github Deployments API for new deployments on a given environment. When a new deployment is found it follows these steps:

- Creates a "pending" Github Deployment Status
- Checks out the code into a "versioned" folder
- Runs the "Before Symlink" steps
- Creates a symbolic link called `current` to the new check out
- Runs the "After Symlink" steps
- Creates a "success" Github Deployment Status

Here is a diagram of how the whole system might look like:
![diagram](docs/diagram.png "Shipper diagram")

### Configuration

A configuration file is required to set up shipper. It uses the [YAML](http://www.yaml.org/) format and it should contain the following parameters:

- `git_url`: The url of the Github repository
- `environment`: The environment the daemon should check for new deployments
- `app_path`: Path of the application
- `server_id`: A unique ID for the server
- `before_symlink`: Array of commands to run before the symlink
- `after_symlink`: Array of commands to run after the symlink
- `shared_files`: A list of shared files to be symlinked
- `keep_revisions`: Revisions to keep when getting ones
- `interval`: Interval between API checks in seconds

A `GH_KEY` environment variable with a [Github Oauth Token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) is currently required to run shipper.
This requirement will be removed for the monitor.

### Commands

#### Setup

Setup the folder structure within the `app_path`. It creates a `releases` and a `shared` folder.

`shipper setup -c shipper.yml`

#### New

Crease a new deployment in the Github API. A `ref` is required.

`shipper new -c shipper.yml --ref master`

#### Run

Run the process that continuously monitors for new deployments.

`shipper run -c shipper.yml`

#### Deploy

Run a manual deployment, if it exists.

`shipper deploy -c shipper.yml`

Imports 5 package(s) ΒΆ

  1. github.com/google/go-github/github
  2. github.com/dlapiduz/httpcache
  3. code.google.com/p/goauth2/oauth
  4. github.com/codegangsta/cli
  5. gopkg.in/yaml.v2