Python interface for talking to the github API
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
github add a newline to the usage message for collabmap Mar 18, 2012
AUTHORS added in general setup structure. Should now work as a normal, instal… Sep 8, 2008
LICENSE added license and copyright information throughout the source Sep 8, 2008
README.markdown Small README fix pointed out by Josh More (thanks!) Oct 10, 2011


What's on Github?

This is a library that implements github's API in python.

Supported APIs

All API access begins with the creation of a GitHub object. For the sake of brevity, this document assumes you've created an object called gh as a github endpoint:

gh = github.GitHub()

Some operations require (or are enhanced by) authentication. These are noted within the documentation and will use an object called agh created the following way:

agh = github.GitHub('myusername', 'mytoken')

You can find your token from your account page.


The user API is available via gh.users.


This is a simple user search call. All properties returned by the API will be available as properties.

Example displaying search results using the name and fullname properties:

for u in
    print("User:  %s (%s)" % (, u.fullname))


Get details about an individual user.

username = 'dustin'
print "%s's web site:  %s" % (username,

Note that this API returns more information if you're authenticated and ask for yourself:

print("My disk usage: %d" %


List your ssh keys:

print "Names of my keys:"
for k in list(agh.users.keys()):


The repository API is available via gh.repos.

Repository List for a User

List the repositories owned by a user. If you are authenticated this user, private repositories will also be returned.

print "My repo names:"
for r in gh.repos.forUser(me):

Branches Within a Repo

List the branches within a repo:

print("memcached branches:")
for branchname, branchhash in gh.repos.branches('dustin', 'memcached'):

Search for a Repository

for r in'memcached'):
    print("%s's %s" % (r.username,

Show a Repository

Retrieve an individual repository.

print('dustin', 'py-github').homepage)

Watch a Repository

Begin watching a repository.'dustin', 'memcached')

Unwatch a Repository

Stop watching a repository.

gh.repos.unwatch('dustin', 'memcached')

Get a Repository's Network

Retrieve the network for a repository.

for r in'dustin', 'memcached'):
    print("%s's %s" % (r.owner,

Adjust a Repository's Visibility

You can adjust repository visibility for your own repositories only (therefore the username is omitted).

To set a repository public:


To set a repository private:

agh.repos.setVisible('repo-name', False)

Create a New Repository

The most simple invocation (create a public repository with no description or URL) would look like this:


You can pass many flags in to set up the repository, however. Consider this case where a private repository is created.

agh.repos.create('testrepo', description='My test repo',
                 homepage='', public=0)

Deleting a Repository

You may delete repositories attached to your account only.


Forking a Repository

agh.repos.fork('dustin', 'memcached')

Adding a Collaborator

agh.repos.addCollaborator('memcached', 'trondn')

Removing a Collaborator

agh.repos.removeCollaborator('memcached', 'trondn')

Listing Deploy Keys


Add a Deploy Key

keyContents = open(os.path.expanduser("~/.ssh/")).read()
agh.repos.addDeployKey('myrepo', 'Key Name', keyContents)

Remove a Deploy Key

agh.repos.removeDeployKey('myrepo', 8582)


The commit API is available via gh.commits.

Get the Commits from a Branch

Master is assumed:

for c in gh.commits.forBranch('dustin', 'py-github'):
    print("%s %s" % ([:7], c.message[:60].split("\n")[0]))

Otherwise, you can specify a branch name:

for c in gh.commits.forBranch('dustin', 'py-github', 'v2'):
    print("%s %s" % ([:7], c.message[:60].split("\n")[0]))

Get the Commits Affecting a File

Retrieve all of the commits for the specified file. Again, master is assumed):

for c in gh.commits.forFile('dustin', 'py-github', 'README.markdown'):
    print("%s %s" % ([:7], c.message[:60].split("\n")[0]))

...but you can also specify a branch name:

for c in gh.commits.forFile('dustin', 'py-github', 'README.markdown', 'v2'):
    print("%s %s" % ([:7], c.message[:60].split("\n")[0]))

Show a Specific Commit

print'dustin', 'memcached',


The issues api is available via gh.issues.

List Repository Issues

for i in gh.issues.list('dustin', 'py-github'):
    print("issue #%s:  %s" % (i.number, i.title))

Show a Particular Issue

i ='dustin', 'py-github', 1)
print("%s:  %s" % (i.state, i.title))

Add a Label to an Issue

agh.issues.add_label('dustin', 'py-github', 38, 'awesome')

Remove a Label from an Issue

agh.issues.remove_label('dustin', 'py-github', 38, 'fun')

Close an Issue

agh.issues.close('dustin', 'py-github', 38)

Reopen a Closed Issue

agh.issues.reopen('dustin', 'py-github', 38)

Create a New Issue'dustin', 'py-github', 'more code', 'Write more code.')

The body parameter (last) is optional.

Edit an Existing Issue

agh.issues.edit('dustin', 'py-github', 8284, 'New Title', 'New Body')


The objects API is available via gh.objects.

Get a Tree

Retreive the tree object with the given hash:

t = gh.objects.tree('dustin', 'py-github',
for k,v in list(t.items()):
    print "%s\t%s\t%s" % (v.sha, v.type, k)

Retrieve a Blob (with info)

b = gh.objects.blob('dustin', 'py-github',
    'b34f658fd7be0d3e00cc961b75da10ca0d44d050', 'README.markdown')

Retrieve a Raw Blob

print b.raw_blob('dustin', 'py-github',


The organizations API is available via gh.organizations.

Getting Organization Information

Get the full information on organizations by the screen name.

org = 'ff0000'
print "%s's location:  %s" % (org,

Updating fields

Owners can update the organization with these fields:

  • name
  • email
  • blog
  • company
  • location
  • billing_email

    org = 'ff0000' print "%s's old location: %s" % (org, agh.organizations.set('ff0000', location='Los Angeles, CA')

Checking Organization Membership

Get all the public organizations that a user is part of. If you are authenticated, concealed memberships will also be returned.

print "My organizations:"
for org in gh.organizations.forUser(me):
    print org

Listing Organization Memberships

List all repositories across all the organizations that you can access.

print "Repositories of my organizations:"
for repo in agh.organizations.repositories():

List all members of the organization's Owners team:

print "Owner of my organization:"
for owner in agh.organizations.owners('ff0000'):

List all public repositories of any other organization:

print "Public repositories of the github organization:"
for repo in gh.organizations.publicRepositories('github'):

List all public members of any organization:

print "Public members of the github organization:"
for member in gh.organizations.publicMembers('github'):