Ruby interface to github API v3
Pull request Compare This branch is 1263 commits behind piotrmurach:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status Dependency Status

Wiki | RDocs

A Ruby wrapper for the GitHub REST API v3.

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


Since version 0.5 the way the gem queries the GitHub api underwent important changes. It closely mirros the Github api hierarchy e.i. if you want to create a download resource, lookup the github api spec and issue the request as in github.repos.downloads.create

Old style: github.pull_requests.create_request

New style: github.pull_requests.create


Install the gem by issuing

gem install github_api

or put it in your Gemfile and run bundle install

gem "github_api"


Create a new client instance

github =

At this stage you can also supply various configuration parameters, such as :user,:repo, :org, :oauth_token, :login, :password or :basic_auth which are used throughout the API

github = oauth_token: 'token'

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

github = login:'peter-murach', password:'...'

or use convenience method:

github = basic_auth: 'login:password'

You can interact with GitHub interface, for example repositories, by issuing 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 =
blobs.create 'peter-murach', 'github', content: 'Blob content'

The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls e.i.

repos = :user => 'peter-murach', :repo => 'github'
repos.branches do |branch|


Main API methods are grouped into the following classes that can be instantiated on their own

Github         - full API access

Github::Gists           Github::GitData       Github::Repos
Github::Orgs            Github::Issues        Github::Authorizations
Github::PullRequests    Github::Users         Github::Events

Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of APIs only for the authenticated user


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

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

For specification on all available methods go to or read the rdoc, all methods are documented there with examples of usage.

Alternatively, you can find out a specific class supported methods by calling actions in your irb:

>> Github::Repos.actions
|--> all
|--> branches
|--> collaborators
|--> commits
|--> contribs
|--> contributors
|--> create
|--> downloads
|--> edit
|--> find
|--> forks
|--> get
|--> hooks

or you can call actions on chained query:

>> github.issues.actions
|--> all
|--> comments
|--> create
|--> edit
|--> events
|--> find
|--> get
|--> labels
|--> list
|--> list_repo
|--> list_repository
|--> milestones


Some API methods apart from required parameters such as username, repository name or organisation name, allow you to switch the way the data is returned to you, for instance

github =
github.git_data.trees.get 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea'
# => gets a tree

github.git_data.trees.get 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea',
  recursive: true # => gets a whole tree recursively

by passing a block you can iterate over the file tree

github.git_data.trees.get 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea',
  recursive: true do |file|
    puts file.path


In order to authenticate the user through OAuth2 on GitHub you need to

github = :client_id => '...', :client_secret => '...'
github.authorize_url :redirect_uri => 'http://localhost', :scope => 'repo'
# => "'...'&redirect_uri=http%3A%2F%2Flocalhost"

After you get your authorization code, call to receive your access_token

token = github.get_token( authorization_code )

Once you have your access token, configure your github instance following instructions under Configuration.

Authorizations API

Alternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API do following

github = 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).

MIME Types

Issues, PullRequests and few other API leverage custom mime types which are :json, :blob, :raw, :text, :html, :full. By default :raw is used.

In order to pass a mime type with your request do

github =
github.pull_requests.list 'peter-murach', 'github', :mime_type => :full

Your header will contain 'Accept: "application/vnd.github-pull.full+json"' which in turn returns raw, text and html representations in response body.


Certain methods require authentication. To get your GitHub OAuth v2 credentials, register an app at You will need to be logged in to register the application.

Github.configure do |config|
  config.oauth_token   = YOUR_OAUTH_ACCESS_TOKEN
  config.basic_auth    = 'login:password'

or => YOUR_OAUTH_TOKEN) => 'login:password')

All parameters can be overwirtten as per method call. By passing parameters hash...

Stack(work in progress)

By default the github_api gem will use the default middleware stack. However, a simple DSL is provided to create a custom stack, for instance:

github = Github.stack do
  request :filter
  request :normalizer
  request :validations

  response :cache do
    register :filestore

  adapter :net_http

By default no caching will be performed. In order to set the cache do... If no cache type is provided a default memoization is done.


Any request that returns multiple items will be paginated to 30 items by default. You can specify custom page and per_page query parameters to alter default behavior. For instance:

res = user: 'wycats', per_page: 10, page: 5

Then you can query pagination information included in the link header by:

res.links.first  # Shows the URL of the first page of results.   # Shows the URL of the immediate next page of results.
res.links.prev   # Shows the URL of the immediate previous page of results.
res.links.last   # Shows the URL of the last page of results.

In order to iterate through the entire result set page by page, you can use convenience methods:

res.each_page do |page|
  page.each do |repo|

or use has_next_page? and next_page like in the following:

while res.has_next_page?
  ... process response ...

One can also navigate straight to specific page by: 5     # Requests given page if it exists, nil otherwise

Response Message

Each response comes packaged with methods allowing for inspection of HTTP start line and headers. For example to check for rate limits and status code issue

res = 'peter-murach', 'github'
res.ratelimit_limit     # "5000"
res.ratelimit_remainig  # "4999"
res.status              # "200"
res.content_type        # "application/json; charset=utf-8"


Some api methods require input parameters, these are added simply as a hash properties, for instance

issues = user:'peter-murach', repo: 'github-api'
issues.milestones.list state: 'open', sort: 'due_date', direction: 'asc'

Other methods may require inputs as an array of strings

users = oauth_token: 'token'
users.emails.add 'email1', 'email2', ..., 'emailn' # => Adds emails to the authenticated user

If a method returns a collection, you can iterator over it by supplying a block parameter,

events =
events.public do |event|

Query requests instead of http responses return boolean values

github =
github.orgs.members.public_member? 'github', 'technoweenie' # => true

Rails Example

A Rails controller that allows a user to authorize their GitHub account and then perform request.

class GithubController < ApplicationController

  def authorize
    github = :client_id => '...', :client_secret => '...'
    address = github.authorize_url :redirect_uri => 'http://...', :scope => 'repo'
    redirect_to address

  def callback
    authorization_code = params[:code]
    token = github.get_token authorization_code
    access_token = token.token


The test suite is split into two groups live and mock.

The live tests are the ones in features folder and they simply exercise the GitHub API by making live requests and then being cached with VCR in directory named features\cassettes. For details on how to get setup please navigate to features folder.

The mock tests are in spec directory and their primary concern is to test the gem internals without the hindrance of external calls.


Questions or problems? Please post them on the issue tracker. You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running bundle and rake.


Copyright (c) 2011-2012 Piotr Murach. See LICENSE.txt for further details.