gitomator 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 71e6ba35da4ab95a835b16f67535443c5eaaf502
+  data.tar.gz: e8bfe6312b250b290b6343fc7305060e651cd96b
+SHA512:
+  metadata.gz: d45742b74bbfc30a3d48f3c34b9d9c20bb6c54acfc6e12b08954cc8166c592aedf1e23cc53a009b57e63f211b8140392a83229768472804823f9449ef7d3a06a
+  data.tar.gz: 6dff541ca6ecb893860ac76b40deba5367d24e958a7b4a96d1f0383ceb367c6314fda4d0f04e9d7b15f57f79ddd63ba6c64ff4373a9209c7589368a5f4b9cb78

data/.gitignore

@@ -0,0 +1,57 @@
+
+# Created by https://www.gitignore.io/api/ruby
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# End of https://www.gitignore.io/api/ruby
+

data/.ruby-gemset

@@ -0,0 +1 @@
+gitomator

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.2.2

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in gitomator.gemspec
+gemspec
+
+#
+# FIXME: The whole point is to be able to plug-in different providers (where the
+#    core project is light, and doesn't know/care/depends on any specific provider).
+#    I still don't know of a clean way to do that in Ruby, so for now let's add
+#    gitomator-github and gitomator-travis as dependencies...
+#
+gem 'gitomator-github', :git => 'git@github.com:Gitomator/gitomator-github.git'
+gem 'gitomator-travis', :git => 'git@github.com:Gitomator/gitomator-travis.git'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Joey Freund
+
+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/README.md

@@ -0,0 +1,194 @@
+# Gitomator
+
+_Gitomator_ is a set of command-line tools for batch operations on hosted Git repositories.      
+
+It was built to help software educators use tools like [GitHub](https://github.com) or [Travis CI](http://travis-ci.com) in their classroom, and here are some of the tasks it can help you with:
+
+ * Create, clone and update repos
+ * Create teams and update team memberships
+ * Set access permissions
+ * Enable/disable CI
+
+
+Think of Gitomator as a _Swiss army knife for your GitHub organization_.
+
+## Dependencies
+
+ * [Ruby](https://www.ruby-lang.org/en/downloads/) (Gitomator is developed and tested on version 2.2)
+ * [Ruby Gems](https://rubygems.org/pages/download)
+
+
+## Installation
+
+```sh
+gem install gitomator
+```
+
+
+## Configure Credentials
+
+Create the `.gitomator` configuration file *in your home directory* with your credential information:
+
+```ruby
+hosting:
+  provider: github
+  access_token: YOUR-GITHUB-ACCESS-TOKEN
+  organization: YOUR-GITHUB-ORGANIZATION
+
+ci:
+  provider: travis_pro
+  access_token: YOUR-TRAVIS-CI-ACCESS-TOKEN
+  github_organization: YOUR-GITHUB-ORGANIZATION
+```
+
+ >  * You can read more about how to [create an access token on GitHub](https://github.com/blog/1509-personal-api-tokens).
+ >  * If you don't use Travis CI, feel free to omit the `ci` configuration
+ >  * You can specify a different path (other than `~/.gitomator`) for you configuration file, by setting the `GITOMATOR_CONTEXT` environment variable.
+ >  * **Important:** Keep your credentials safe!      
+      The `.gitomator` file is local to your machine, and should *not* be committed to version control.
+
+## Examples
+
+Let's see a few basic usage examples.
+
+### Create repos
+
+You can create a bunch of empty repos in your organization, by creating the following [YAML](https://en.wikipedia.org/wiki/YAML) file:
+
+```ruby
+repos:
+ - repo_01
+ - repo_02
+ - repo_03
+```
+
+And running the following command:
+
+```sh
+gitomator-make-repos PATH-TO-YAML-FILE
+```
+
+ > You can change the YAML file and re-run the `gitomator-make-repos`, Gitomator will create repos that are missing.
+
+
+If you want the repos to be created with initial starter code, you could add the `source_repo` field to the YAML file:
+
+```ruby
+source_repo: name_of_some_repo_in_your_organization
+
+repos:
+ - repo_01
+ - repo_02
+ - repo_03
+```
+
+ > * When Gitomator creates the repositories, it will push all the commits from the specified repo.
+ > * If you are new to GitHub you may want to read about [the difference between forking and cloning-then-pushing](https://education.github.com/guide/repository_setup).
+
+
+You can also specify various properties of created repositories, by adding the `repo_properties` field to the YAML file:
+
+```ruby
+source_repo: name_of_some_repo_in_your_organization
+
+repo_properties:
+  description: "A short description"
+  homepage: "http://example.com"
+  private: true
+  has_issues: true
+  has_wiki: false
+  has_downloads: false
+  default_branch: master
+
+repos:
+ - repo_01
+ - repo_02
+ - repo_03
+```
+
+### Update repos
+
+You can update repos by updating the source repo (i.e. the repo that contains the starter code) and then run `gitomator-make-repos` with the `-u` option:
+
+```sh
+gitomator-make-repos -u PATH-TO-YAML-FILE
+```
+
+ > * Such a batch update is only possible when all repos have the same commit history.
+ > * You can run `gitomator-make-repos` with `--help` for more information.
+
+
+### Manage Access Permissions
+
+You can specify who gets which permission to which repo in (the `repos` section
+of) the same YAML file we've been using:
+
+```ruby
+repos:
+ - repo_01 : user_01
+ - repo_02 : user_02
+ - repo_03 : [user_03, user_04]
+```
+
+And run:
+
+```sh
+gitomator-make-access-permissions PATH-TO-YAML-FILE
+```
+
+#### Users vs. Teams
+
+You can use the `-p` option to specify whether the names in the YAML files refer
+to users or teams. The following values are accepted:
+
+ * `user`  - Names in the YAML file refer to users (this is the default)
+ * `team`  - Names in the YAML file refer to teams
+ * `mixed` - Let Gitomator figure out which name refers to a team and which refers to a user.
+
+
+#### Read vs. Write
+
+By default, Gitomator gives the specified users/teams read permission,
+but you can specify otherwise in the YAML file:
+
+```ruby
+repos:
+ - repo_01 : {user_01: write}
+ - repo_02 : [{user_02: write}, user_07]
+ - repo_03 : [team_01, {admin_01: write}]
+```
+
+
+### Clone repos
+
+You can clone repos to your local machine using the `gitomator-clone-repos` command:
+
+```sh
+gitomator-clone-repos PATH-TO-YAML-FILE LOCAL-DIR
+```
+
+ > The YAML file has the same format as expected by the `gitomator-clone-repos` command.
+
+
+### Manage teams
+
+You can create teams and update team memberships with the `gitomator-make-teams` command,
+which takes a YAML of the following format:
+
+```ruby
+team_01:
+ - user_01
+ - user_02
+ - user_03
+
+team_02:
+ - user_01
+ - user_07
+```
+
+When you run `gitomator-make-teams`, Gitomator will:
+ * Create all missing teams (in your GitHub organization)
+ * Add all missing team memberships
+
+ > Users who are not yet members of your GitHub organization, will automatically
+   get an email invite to join.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new
+rescue LoadError
+end
+
+task :test => :spec

data/bin/gitomator-clone-repos

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/clone_repos'
+require 'gitomator/task/config/repos_config'
+
+usage_message  = "Usage: #{File.basename($0)} REPOS-CONFING LOCAL-DIR"
+opts = Gitomator::ScriptUtil::DefaultOptionParser.new(usage_message).parse(ARGV)
+abort usage_message if ARGV.length != 2
+
+context     = Gitomator::Context.from_file(opts[:context])
+
+config_hash = Gitomator::Util.load_config(ARGV[0])
+task_config = Gitomator::Task::Config::ReposConfig.new(config_hash)
+local_dir   = ARGV[1]
+
+Gitomator::ScriptUtil::run_task(
+  Gitomator::Task::CloneRepos.new(context, task_config.repos, local_dir)
+)

data/bin/gitomator-console

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/console'
+require 'gitomator/context'
+require 'irb'
+
+usage_message  = "Usage: #{File.basename($0)}"
+opts = Gitomator::ScriptUtil::DefaultOptionParser.new(usage_message).parse(ARGV)
+abort usage_message if ARGV.length != 0
+
+
+Gitomator::Console::context = Gitomator::Context.from_file(opts[:context])
+
+
+include Gitomator::Console
+
+IRB.start

data/bin/gitomator-disable-ci

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/enable_disable_ci'
+require 'gitomator/task/config/repos_config'
+
+usage_message  = "Usage: #{File.basename($0)} REPOS-CONFING"
+parser = Gitomator::ScriptUtil::DefaultOptionParser.new(usage_message)
+parser.opt(:sync, "Synchronize the CI service.")
+opts = parser.parse(ARGV)
+abort usage_message if ARGV.length != 1
+
+context = Gitomator::Context.from_file(opts[:context])
+
+config_hash  = Gitomator::Util.load_config(ARGV[0])
+repos_config = Gitomator::Task::Config::ReposConfig.new(config_hash)
+
+task_opts = { :sync => opts[:sync] }
+
+Gitomator::ScriptUtil::run_task(
+  Gitomator::Task::DisableCI.new(context, repos_config.repos, task_opts)
+)

data/bin/gitomator-enable-ci

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/enable_disable_ci'
+require 'gitomator/task/config/repos_config'
+
+usage_message  = "Usage: #{File.basename($0)} REPOS-CONFING"
+parser = Gitomator::ScriptUtil::DefaultOptionParser.new(usage_message)
+parser.opt(:sync, "Synchronize the CI service.")
+opts = parser.parse(ARGV)
+abort usage_message if ARGV.length != 1
+
+context = Gitomator::Context.from_file(opts[:context])
+
+config_hash  = Gitomator::Util.load_config(ARGV[0])
+repos_config = Gitomator::Task::Config::ReposConfig.new(config_hash)
+
+task_opts = { :sync => opts[:sync] }
+
+Gitomator::ScriptUtil::run_task(
+  Gitomator::Task::EnableCI.new(context, repos_config.repos, task_opts)
+)

data/bin/gitomator-make-access-permissions

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/update_repo_access_permissions'
+require 'gitomator/task/config/repos_config'
+
+usage_message  = "Usage: #{File.basename($0)} REPOS-CONFING"
+banner = <<-EOS
+Command-line tool to update access permissions (who gets what access-permission to which repos).
+
+  #{usage_message}
+
+EOS
+
+parser = Gitomator::ScriptUtil::DefaultOptionParser.new(banner)
+parser.opt :permission_type,
+  "One of 'user', 'team' or 'mixed'.\nIndicates whether the names in the " +
+  "configuration files are usernames, team names, or a mix of both " +
+  "(in which case the script will first look for team with the specified name).",
+  :default => 'user'
+
+opts = parser.parse(ARGV)
+
+parser.die :type, "Type must be one of 'user', 'team' or 'mixed'" unless ['user','team','mixed'].include? opts[:permission_type]
+abort usage_message if ARGV.length != 1
+
+
+
+context     = Gitomator::Context.from_file(opts[:context])
+config_hash = Gitomator::Util.load_config(ARGV[0])
+task_config = Gitomator::Task::Config::ReposConfig.new(config_hash)
+
+#-------------------------------------------------------------------------------
+# Actual script ...
+
+tasks = []
+
+# If the permission is mixed, we should cache all team names
+# For every name we encounter, we will check if it's a team's name.
+team_names = nil
+if opts[:permission_type] == 'mixed'
+  team_names = context.hosting.search_teams('').map {|t| t.name}
+end
+
+
+task_config.repos.each do |repo|
+  user2permission = {}
+  team2permission = {}
+
+  # The names in the assignment config might be usernames, team names, or a mix of both.
+  case opts[:permission_type]
+  when 'user'
+    user2permission = task_config.permissions(repo)
+  when 'team'
+    team2permission = task_config.permissions(repo)
+  when 'mixed'
+    task_config.permissions(repo).each do |name, permission|
+      if team_names.include? name
+        team2permission[name] = permission
+      else
+        user2permission[name] = permission
+      end
+    end
+  end
+
+  tasks.push Gitomator::Task::UpdateRepoAccessPermissions.new(
+                              context, repo, user2permission, team2permission)
+end
+
+Gitomator::ScriptUtil::run_tasks(tasks)

data/bin/gitomator-make-repos

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/make_repos'
+require 'gitomator/task/config/repos_config'
+
+usage_message  = "Usage: #{File.basename($0)} REPOS-CONFING"
+banner = <<-EOS
+Command-line tool to create repos based on a configuration file.
+
+  #{usage_message}
+
+Repos can be created empty, or based on an existing source_repo (specified in the configuration file).
+EOS
+
+parser = Gitomator::ScriptUtil::DefaultOptionParser.new(banner)
+parser.opt :update_existing,
+    "Update existing repos by pushing recent changes from the source_repo",
+    :default => false
+
+opts = parser.parse(ARGV)
+abort usage_message if ARGV.length != 1
+
+context     = Gitomator::Context.from_file(opts[:context])
+
+config_hash = Gitomator::Util.load_config(ARGV[0])
+task_config = Gitomator::Task::Config::ReposConfig.new(config_hash)
+
+task_opts = {}
+if task_config.source_repo
+  task_opts[:source_repo] = task_config.source_repo
+end
+if task_config.repo_properties
+  task_opts[:repo_properties] = task_config.repo_properties.map {|k,v| [k.to_sym,v]} .to_h
+end
+if opts[:update_existing]
+  task_opts[:update_existing] = true
+end
+
+
+Gitomator::ScriptUtil::run_task(
+  Gitomator::Task::MakeRepos.new(context, task_config.repos, task_opts)
+)

data/bin/gitomator-make-teams

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'gitomator/util/script_util'
+require 'gitomator/context'
+require 'gitomator/task/setup_team'
+require 'gitomator/task/config/team_config'
+
+usage_message  = "Usage: #{File.basename($0)} TEAMS-CONFING"
+opts = Gitomator::ScriptUtil::DefaultOptionParser.new(usage_message).parse(ARGV)
+abort usage_message if ARGV.length != 1
+
+context     = Gitomator::Context.from_file(opts[:context])
+config_hash = Gitomator::Util.load_config(ARGV[0])
+
+Gitomator::Task::Config::TeamConfig::from_hash(config_hash).each do |team|
+  Gitomator::ScriptUtil::run_task(
+    Gitomator::Task::SetupTeam.new(context, team.name, team.members)
+  )
+end

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/gitomator.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gitomator/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gitomator"
+  spec.version       = Gitomator::VERSION
+  spec.authors       = ["Joey Freund"]
+  spec.email         = ["joeyfreund@gmail.com"]
+
+  spec.summary       = "Automation tools for Git repo  organizations."
+  spec.homepage      = "https://github.com/gitomator/gitomator"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+
+  spec.add_runtime_dependency 'trollop', '~> 2.1', '>= 2.1.2'
+  spec.add_runtime_dependency 'logger', '~> 1.2', '>= 1.2.8'
+
+end

data/lib/gitomator/console.rb

@@ -0,0 +1,54 @@
+require "gitomator/version"
+
+module Gitomator
+  module Console
+
+
+    def self.context=(context)
+      @context = context
+    end
+
+    def self.context()
+      @context
+    end
+
+    # ====================== Convenience Console Functions =====================
+
+    def gitomator_version
+      Gitomator::VERSION
+    end
+
+    def gitomator_context
+      Gitomator::Console::context
+    end
+
+
+    # --------------------------------------------------------------------------
+
+    def search_repos(query)
+      gitomator_context.hosting.search_repos(query).map {|r| r.full_name}
+    end
+
+    def delete_repo(repo_name)
+      gitomator_context.hosting.delete_repo(repo_name)
+    end
+
+
+
+    def search_teams(query)
+      gitomator_context.hosting.search_teams(query).map {|t| t.name}
+    end
+
+    def delete_team(team_name)
+      gitomator_context.hosting.delete_team(team_name)
+    end
+
+
+    def list_team_members(team_name)
+      gitomator_context.hosting
+        .search_users('', { team_name: team_name }).map {|u| u.username}
+    end
+
+
+  end
+end