github-collective 0.4

Introduction

GitHub organizations are great way for organizations to manage their Git repositories. This tool will let you automate the tedious tasks of creating teams, granting permissions, and creating repositories or modifying their settings.

The approach that the github-collective tool takes is that you edit a central configuration (currently an ini-like file) from where options are read and synchronized to GitHub respectively.

Initially, the purpose of this script was to manage Plone’s collective organization on GitHub: http://collective.github.com. It is currently in use in several other locations.

Documentation

Read the full documentation at http://github-collective.rtfd.org.

Features

• Create one central configuration that you can sync to GitHub to configure your organisation’s settings, repositories, teams, and more.

  • Combine this with GitHub’s fork-and-pull request model to easily allow non-administrative users to create and manage repositories with minimal overhead.

• Repositories: create and modify repositories within an organization

  • Configure all repository properties as per the GitHub Repos API, including privacy (public/private), description, and other metadata.

  • After the initial repository creation happens, updated values in your configuration will replace those on GitHub.

• Service hooks: add and modify service hooks for repositories.

  • GitHub repositories have support for sending information upon certain events taking place (for instance, pushes being made to a repository or a fork being taken).

  • After the initial repo creation process takes place, updated values in your hook configuration will replace those on GitHub.

  • Hooks not present in your configuration (such as those manually added on GitHub or those removed from local configuration) will not be deleted.

• Teams: automatically create teams and modify members

  • Control permissions for teams (for example: push, pull or admin)

• Automatically syncs all of the above with GitHub when the tool is run.

• Buildout-style variable substitution in the form ${section:option}.

Usage

When github-collective is installed it should create an executable with same name in your bin directory.

% bin/github-collective --help
usage: github-collective [-h] -c CONFIG [-M MAILER] [-C CACHE] -o GITHUB_ORG
                         -u GITHUB_USERNAME -P GITHUB_PASSWORD [-v] [-p]

This tool will let you automate tedious tasks of creating teams granting
permission and creating repositories.

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        path to configuration file (could also be remote
                        location). eg.
                        http://collective.github.com/permissions.cfg (default:
                        None)
  -M MAILER, --mailer MAILER
                        TODO (default: None)
  -C CACHE, --cache CACHE
                        path to file where to cache results from github.
                        (default: None)
  -o GITHUB_ORG, --github-org GITHUB_ORG
                        github organisation. (default: None)
  -u GITHUB_USERNAME, --github-username GITHUB_USERNAME
                        github account username. (default: None)
  -P GITHUB_PASSWORD, --github-password GITHUB_PASSWORD
                        github account password. (default: None)
  -v, --verbose
  -p, --pretend

% bin/github-collective \
    -c example.cfg \ # path to configuration file
    -o vim-addons \  # organization that we are
    -u garbas \      # account that has management right for organization
    -P PASSWORD      # account password

% bin/github-collective \
    -c https://raw.github.com/collective/github-collective/master/example.cfg \
                     # url to configuration file
    -o collective \  # organization that we are
    -u garbas \      # account that has management right for organization
    -P PASSWORD      # account password

% bin/github-collective \
    -c https://raw.github.com/collective/github-collective/master/example.cfg \
                     # url to configuration file
    -C .cache        # file where store and read cached results from github
    -o collective \  # organization that we are
    -u garbas \      # account that has management right for organization
    -P PASSWORD      # account password

Testing

nose is utilised for testing and configuration for nose exists within the setup.cfg file within this project. This configuration automatically examines files for tests within the project, including this read-me itself. You can initialise and run tests using the Buildout configuration provided:

git clone git://github.com/collective/github-collective.git
cd github-collective
virtualenv .
python boostrap.py
bin/buildout
bin/nosetests

tox is used to ensure this package installs correctly under each version of Python. Currently we test Python 2.6 and Python 2.7. Support for running tests under tox will come shortly. To test installation:

git clone git://github.com/collective/github-collective.git
cd github-collective
virtualenv .
pip install tox
tox

Issues and Contributing

Report issues via this project’s GitHub issue tracker at https://github.com/collective/github-collective/issues.

Contribute by submitting a pull request on GitHub or else by adding yourself to the Collective and contributing directly.

Todo

• Allow configuration of organisation settings via API

• Add facility to continue if error experienced

• Send emails to owners about removing repos

• Better logging mechanism (eg. logbook)

• Support configuration extensibility (eg extends = syntax) for using multiple configuration files.

Credits

Author:

Rok Garbas (garbas)

Contributor:

David Beitey (davidjb)

Changelog