Unicorn • A place for open source creatures

Features

Supports all the API methods. It's build in a modular way, that is, you can either instantiate the whole api wrapper Github.new or use parts of it e.i. Github::Repos.new if working solely with repositories is your main concern.

Intuitive GitHub API interface navigation.
Modular design allows for working with parts of API.
Fully customizable including advanced middleware stack construction.
Its comprehensive, you can request all GitHub API resources.
Requests pagination with convenient DSL and automatic option.
Support OAuth2 authorization.

Flexible arguments parsing, you can write expressive and natural queries.
Easy error handling split for client and server type errors.
Supports multithreaded environment.
Custom media types specification through ‘media’ parameter.
Request results caching.
Fully tested with test coverage above 90% with over 1,600 specs and 900 features.

Usage & Installation

Install the gem by issuing

$ gem install github_api

or put it in your Gemfile and run bundle install

gem "github_api"

To start using the gem you can either perform direct call on the Github

Github.repos.list user: 'wycats'

or create a new client instance

github = Github.new

Application Interface

This library closely mirrors the GitHub Api hierarchy. For example to interact with GitHub Repositories API, issue the following calls that correspond directly to the GitHub API hierarchy

github.repos.commits.all  'user-name', 'repo-name'
github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
github.repos.keys.get     'user-name', 'repo-name'

The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. blobs

blobs = Github::GitData::Blobs.new
blobs.create 'piotrmurach', 'github', content: 'Blob content'

The response is of type Github::ResponseWrapper and allows to traverse all the json response attributes like method calls e.i.

repos = Github::Repos.new :user => 'piotrmurach', :repo => 'github'
repos.branches do |branch|
  puts branch.name
end

All method calls form ruby like sentences and allow for intuitive api navigation, for instance

github = Github.new :oauth_token => '...'
github.users.followers.following 'wycats'  # => returns users that 'wycats' is following
github.users.followers.following? 'wycats' # => returns true if following, otherwise false

The library allows for flexible arguments parsing. Therefore arguments can be passed during instance creation

issues = Github::Issues.new user: 'piotrmurach', repo: 'github'
issues.milestones.list state: 'open'

Configuration

At this stage you can also supply various configuration parameters, such as

  adapter          # http client used for performing requests
  auto_pagination  # by default false, set to true traverses requests page links
  oauth_token      # oauth authorization token
  basic_auth       # login:password string
  client_id        # oauth client id
  client_secret    # oauth client secret
  user             # global user used in requets if none provided
  repo             # global repository used in requests in none provided
  org              # global organization used in request if none provided
  endpoint         # enterprise api endpoint
  site             # enterprise api web endpoint
  ssl              # ssl settings
  per_page         # number of items per page, max 100
  user_agent       # custom user agent name, by default 'Github API'

which are used throughout the API. These can be passed directly as hash options:

github = Github.new oauth_token: 'token'

Alternatively, you can configure the Github settings by passing a block, for instance, with custom enterprise endpoint and website like

github = Github.new do |config|
  config.endpoint    = 'https://github.company.com/api/v3'
  config.site        = 'https://github.company.com'
  config.oauth_token = 'token'
  config.adapter     = :net_http
  config.ssl         = {:verify => false}
end

The github_api gem will use the default middleware stack which is exposed by calling stack on client instance. However, this stack can be freely modified with methods such as insert, insert_after, delete and swap. For instance to add your CustomMiddleware do

github = Github.new do |config|
  config.stack.insert_after Github::Response::Helpers, CustomMiddleware
end

Authorization

You can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials

github = Github.new login:'piotrmurach', password:'...'

or use convenience method

github = Github.new basic_auth: 'login:password'

Alternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API you required to pass your basic credentials as in the following:

github = Github.new basic_auth: 'login:password'
github.oauth.create 'scopes' => ['repo']

You can add more than one scope from the user, public_repo, repo, gist or leave the scopes parameter out, in which case, the default read-only access will be assumed(includes public user profile info, public repo info, and gists).

Command Line Interface

If your preference is to have CLI-based access to GitHub API v3, you can use a ruby gem called github_cli.

To install it do

$ gem install github_cli

To run it execute command

$ gcli

The first step is to create a configuration file, either global in home directory or local inside the project:

$ gcli init [--local] [filename]

Without any options this command will setup a .githubrc configuration file in your home/project directory with all the global settings. By passing --local option the config file will be created locally in the execution directory. Further, by default .githubrc name is used which can be changed by passing the filename.

Main configuration options are:

user.token            # Authentication token
user.login            # User login
user.password         # User password
user.name             # Default user name
user.repo             # Default repo name
user.org              # Default organization name
core.editor           # Editor to be opened
core.endpoint         # The api endpoint, by deafult https://api.github.com
core.site             # The web endpoint, by default https://github.com
core.pager            # Pager to be used, by default less
core.format           # Output formating
core.quiet            # Surpass output to show only response status
core.ssl              # SSL settings
core.auto_pagination  # Switch on default results pagination, default false

Moreover, gcli config command allows you to set/get any configuration option such as output format, editor or oauth token.

For instance, to check value for your authentication token do

$ gcli config [--local] user.token

and to set the value do