persephone

README.md

Persephone

Persephone provides a HTTP-based, RESTful web API wrapper around Capistrano tasks. The intent is to allow Capistrano tasks to be executed via web interfaces, chat bots, native applications, etc. without having to manually SSH in to a server and issue commands.

Installation

Persephone is a simple Sinatra app that is distributed as a gem.

Add the gem to your Gemfile:

gem "persephone", "~> 0.0.1"

And run bundle install to install it.

In your config.ru:

require 'persephone'

run Persephone::App

Start the server with Rack:

$ rackup -p 4567

In production, we recommend using an application server such as Unicorn or Thin.

Configuration

Configuration is handled by the config/config.yml file.

GitHub organization

config:
  github:
    organization: proclus

Available tasks

By default Persephone won't be able to access any of your tasks. This is by design. Tasks must be whitelisted in config/config.yml:

config:
  tasks:
    - deploy
    - describe

Projects

"Projects" are Persephone's notion of different libraries of tasks for different apps. These are also specified in config/config.yml:

config:
  projects:
    proclus:
      name: "Proclus Global"
      tasks:
        - deploy
        - describe
    kobol:
      name: "Kobol Engineering"
      tasks:
        - deploy
        - describe

As you can see, projects can have their own sets of available tasks. If you define tasks for a project, this list replaces the global tasks list.

Usage

Start a job

POST /jobs
Host: https://persephone.yourdomain.com
Authorization: Token token="..."

{
  "job": {
    "task": "deploy",
    "site": "kobol",
    "arguments": {
      "branch": "my-feature"
    }
  }
}