add-to-org 2.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82b5c39679b1c2a027a7e88d6e89ac6f2bb51943
-  data.tar.gz: dfed027da8d511c120088cfaf1499f57d7e8323b
+  metadata.gz: 1a99e18aeff2a09664bc9027c2a846413627aa65
+  data.tar.gz: 9114cbaa5a4dc8505d148460ad5bcf24585bac2d
 SHA512:
-  metadata.gz: da885134a8f2dae8e38fdeda232e35ddc30476a5664770b5e894a7c32ce385e98e1cb3d29da71ce7627fb0180a419fc53249233ea9846879adfcb5d7695c0b89
-  data.tar.gz: 9c6b02fce59bdcc578a83804b72880d70ea2d6f58088abe7acccafd8cd24781766601ac3a48cff5a795d78b1199cef81c64af8145bd940270bc65542f3552884
+  metadata.gz: a00ca8dd28bf2f8b0fc6e68dbfc56076c5355af8aff911aedbd7526d38b0248f1968dc51a0930eefa3e5c93eae5227137762a443f30b7f6329e969eff86541c5
+  data.tar.gz: 90005db4a120915bbec411040cf82bdf8c6c514a3a6e00f87ad437f4dda801844a4c8ad2f56d13eb37658b5911ade07589dab211f4ff058a5b556c5dc1afa062

data/.bowerrc

@@ -0,0 +1,3 @@
+{
+  "directory": "lib/add-to-org/public/vendor"
+}

data/.gitignore

@@ -2,3 +2,10 @@
 .bundle
 *.gem
 Gemfile.lock
+/lib/add-to-org/public/vendor/jquery
+/lib/add-to-org/public/vendor/bootstrap/grunt
+/lib/add-to-org/public/vendor/bootstrap/js
+/lib/add-to-org/public/vendor/bootstrap/less
+/lib/add-to-org/public/vendor/bootstrap/nuget
+/lib/add-to-org/public/vendor/bootstrap/*.md
+/lib/add-to-org/public/vendor/bootstrap/*.js

data/.ruby-version

@@ -1 +1 @@
-2.2.3
+2.3.0

data/README.md

@@ -10,10 +10,35 @@ Once set up, simply swap out your app's domain for any GitHub URL. E.g., `github
 
 ## Setup
 
-1. Create [an oauth app](github.com/settings/applications/new)
-2. Create a personal access token for a user with admin rights to the organization
+*Pro-tip: for a quickstart on how to set up the app, see the [add-to-org demo app](https://github.com/benbalter/add-to-org-demo).*
+
+### Credentials
+
+You'll need a few different credentials for things to work:
+
+#### A bot account
+
+You'll need a dedicated "bot" account to add users to the organization:
+
+1. [Create a bot account](https://github.com/signup) (a standard GitHub account not used by a human) that has *admin* rights to your organization.
+2. [Create a personal access token](https://github.com/settings/tokens/new) for that user, with `admin:org` scope.
+
+#### An OAuth application
+
+You'll also need to create an OAUth application to validate users:
+
+1. Create an OAauth application *within your organization* via `https://github.com/organizations/[YOUR-ORGANIZATION-NAME]/settings/applications/new`
+2. The homepage URL should be the URL to your production instance.
+3. You can leave the callback URL blank. The default is fine.
+
+## Developing locally and deploying
+
+*Pro-tip: for a quickstart on how to set up the app, see the [add-to-org demo app](https://github.com/benbalter/add-to-org-demo)*
+
+1. Create [an oauth app](github.com/settings/applications/new) (see above)
+2. Create a personal access token for a user with admin rights to the organization (see above)
 3. Add `gem 'add-to-org' to your project's Gemfile
-4. Add the following to a `config.ru` file:
+4. Add the following to your project's `config.ru` file:
 
 ```ruby
 require 'add-to-org'
@@ -31,40 +56,58 @@ The following environmental values should be set:
 * `GITHUB_TOKEN` - A personal access token for a user with admin rights to the organization
 * `CONTACT_EMAIL` - Point of contact to point users to if something goes wrong
 
-You'll also need to monkey patch a validation method to determine if a user should be added, e.g.:
+### Customizing the validator
+
+For Add to Org to work, you'll also need to define a custom validator. You can do this in your `configu.ru`, or in a separate file included into `config.ru`. Here's an example of a validator that confirms the user has a verified `@github.com` email address:
 
 ```ruby
 require 'add-to-org'
 
-module AddToOrg
-  class App < Sinatra::Base
-    def valid?
-      verified_emails.any? { |email| email[:email] =~ /@github\.com$/}
-    end
-  end
+AddToOrg.set_validator do |github_user, verified_emails, client|
+  verified_emails.any? { |email| email[:email] =~ /@github\.com\z/ }
 end
+
+run AddToOrg::App
 ```
 
-## Customizing Views
+If you prefer, you can also pass the validator as a proc (or lambda):
+
+```ruby
+AddToOrg.validator = proc { |github_user, verified_emails, client|
+  verified_emails.any? { |email| email[:email] =~ /@github\.com\z/ }
+}
+```
 
-There are three views, `success`, `forbidden`, and `error`. They're pretty boring by default, so you may want to swap them out for something a bit my snazzy. There are two ways to do that:
+The validator will receive three  arguments to help you validate the user meets your criteria:
+
+* `github_user` - the Warden user, which will contain information like username, company, and human-readable name
+* `verified_emails` - an array of the user's verified emails
+* `client` - An [Octokit.rb](https://github.com/octokit/octokit.rb) client, preset with the user's OAuth token.
+
+The validator should return `true` if you'd like the current user added to the organization, or `false` if you'd like the user's request to be denied.
+
+### Customizing Views
+
+There are three views, `success`, `forbidden`, and `error`. They're pretty boring by default, so you may want to swap them out for something a bit my snazzy. If you had a views directory along side your `config.ru`, you can do so like this in your `config.ru` file:
 
 ```ruby
-module AddToOrg
-  class App < Sinatra::Base
-    set :views, "path/to/your/views"
-  end
-end
+require 'add-to-org'
+
+AddToOrgs.views_dir = File.expand_path("./views", File.dirname(__FILE__))
+
+run AddToOrg::App
 ```
 
-or by overwriting the `success`, `forbidden`, and `error` methods entirely:
+These are just sinatra `.erb` views. Take a look at [the default views](https://github.com/benbalter/add-to-org/tree/master/lib/add-to-org/views) for an example.
+
+### Customizing static assets
+
+You can also do the same with `AddToOrg.public_dir` for serving static assets (AddToOrg comes bundled with Bootstrap by default).
 
 ```ruby
-module AddToOrg
-  class App < Sinatra::Base
-    def success(locals={})
-      halt erb :some_template, :locals => locals
-    end
-  end
-end
+require 'add-to-org'
+
+AddToOrgs.public_dir = File.expand_path("./public", File.dirname(__FILE__))
+
+run AddToOrg::App
 ```

data/bower.json

@@ -0,0 +1,15 @@
+{
+  "name": "add-to-org",
+  "homepage": "https://github.com/benbalter/add-to-org",
+  "authors": [
+    "Ben Balter <ben.balter@github.com>"
+  ],
+  "description": "A simple Oauth App to automatically add users to an organization",
+  "main": "script/server",
+  "moduleType": [],
+  "license": "MIT",
+  "private": true,
+  "dependencies": {
+    "bootstrap": "~3.3.6"
+  }
+}

data/lib/add-to-org/helpers.rb

@@ -1,31 +1,33 @@
 module AddToOrg
   module Helpers
 
+    # query api for the user's verified emails
+    def verified_emails
+      emails = client.emails :accept => 'application/vnd.github.v3'
+      emails.select { |email| email.verified }
+    end
+
+    def valid?
+      AddToOrg.validator.call(github_user, verified_emails, client)
+    end
+
+    private
+
     # user client
     def client
       @client ||= Octokit::Client.new :access_token => github_user.token
     end
 
-    # new org admin client
+    # org admin client
     def sudo_client
       @sudo_client ||= Octokit::Client.new :access_token => ENV['GITHUB_TOKEN']
     end
 
-    # query api for the user's verified emails
-    def verified_emails
-      emails = client.emails :accept => 'application/vnd.github.v3'
-      emails.select { |email| email.verified }
-    end
-
     # true if user is already a member of the org
     def member?
       client.organization_member? org_id, github_user.login
     end
 
-    def valid?
-      raise "You must define a custom valid? method to determine eligibility"
-    end
-
     def team_id
       ENV['GITHUB_TEAM_ID']
     end

data/lib/add-to-org/public/vendor/bootstrap/.bower.json

@@ -0,0 +1,45 @@
+{
+  "name": "bootstrap",
+  "description": "The most popular front-end framework for developing responsive, mobile first projects on the web.",
+  "keywords": [
+    "css",
+    "js",
+    "less",
+    "mobile-first",
+    "responsive",
+    "front-end",
+    "framework",
+    "web"
+  ],
+  "homepage": "http://getbootstrap.com",
+  "license": "MIT",
+  "moduleType": "globals",
+  "main": [
+    "less/bootstrap.less",
+    "dist/js/bootstrap.js"
+  ],
+  "ignore": [
+    "/.*",
+    "_config.yml",
+    "CNAME",
+    "composer.json",
+    "CONTRIBUTING.md",
+    "docs",
+    "js/tests",
+    "test-infra"
+  ],
+  "dependencies": {
+    "jquery": "1.9.1 - 2"
+  },
+  "version": "3.3.6",
+  "_release": "3.3.6",
+  "_resolution": {
+    "type": "version",
+    "tag": "v3.3.6",
+    "commit": "81df608a40bf0629a1dc08e584849bb1e43e0b7a"
+  },
+  "_source": "git://github.com/twbs/bootstrap.git",
+  "_target": "~3.3.6",
+  "_originalSource": "bootstrap",
+  "_direct": true
+}

data/lib/add-to-org/public/vendor/bootstrap/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2015 Twitter, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/add-to-org/public/vendor/bootstrap/bower.json

@@ -0,0 +1,34 @@
+{
+  "name": "bootstrap",
+  "description": "The most popular front-end framework for developing responsive, mobile first projects on the web.",
+  "keywords": [
+    "css",
+    "js",
+    "less",
+    "mobile-first",
+    "responsive",
+    "front-end",
+    "framework",
+    "web"
+  ],
+  "homepage": "http://getbootstrap.com",
+  "license": "MIT",
+  "moduleType": "globals",
+  "main": [
+    "less/bootstrap.less",
+    "dist/js/bootstrap.js"
+  ],
+  "ignore": [
+    "/.*",
+    "_config.yml",
+    "CNAME",
+    "composer.json",
+    "CONTRIBUTING.md",
+    "docs",
+    "js/tests",
+    "test-infra"
+  ],
+  "dependencies": {
+    "jquery": "1.9.1 - 2"
+  }
+}