Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

676 lines (494 sloc) 15.176 kb


octonode is a library for nodejs to access the github v3 api


npm install octonode


var github = require('octonode');

// Then we instanciate a client with or without a token (as show in a later section)

var ghme   =;
var ghuser = client.user('pksunkara');
var ghrepo = client.repo('pksunkara/hub');
var ghorg  ='flatiron');
var ghgist = client.gist();
var ghteam =;

Build a client which accesses any public information

var client = github.client();

client.get('/users/pksunkara', function (err, status, body) {
  console.log(body); //json object

Build a client from an access token

var client = github.client('someaccesstoken');

client.get('/user', function (err, status, body) {
  console.log(body); //json object

Build a client from credentials

var client = github.client({
  username: 'pksunkara',
  password: 'password'

client.get('/user', function (err, status, body) {
  console.log(body); //json object

Many of the below use cases use parts of the above code


Authenticate to github in cli mode (desktop application)

  username: 'pksunkara',
  password: 'password'
}).login(['user', 'repo', 'gist'], function (err, id, token) {
  console.log(id, token);

Revoke authentication to github in cli mode (desktop application)

  username: 'pksunkara',
  password: 'password'
}).revoke(id, function (err) {
  if (err) throw err;

Authenticate to github in web mode (web application)

// Web application which authenticates to github
var http = require('http')
  , url = require('url')
  , qs = require('querystring')
  , github = require('octonode');

// Build the authorization config and url
var auth_url = github.auth.config({
  id: 'mygithubclientid',
  secret: 'mygithubclientsecret'
}).login(['user', 'repo', 'gist']);

// Web server
http.createServer(function (req, res) {
  uri = url.parse(req.url);
  // Redirect to github login
  if (uri.pathname=='/login') {
    res.writeHead(301, {'Content-Type': 'text/plain', 'Location': auth_url})
    res.end('Redirecting to ' + auth_url);
  // Callback url from github login
  else if (uri.pathname=='/auth') {
    github.auth.login(qs.parse(uri.query).code, function (err, token) {
    res.writeHead(200, {'Content-Type': 'text/plain'})
  } else {
    res.writeHead(200, {'Content-Type': 'text/plain'})

console.log('Server started on 3000');

API Callback Structure

All the callbacks for the following will take first an error argument, then a data argument, like this:, data) {
  console.log("error: " + err);
  console.log("data: " + data);

Github authenticated user api

Token/Credentials required for the following:

Get information about the user (GET /user); //json

Update user profile (PATCH /user)

  "name": "monalisa octocat",
  "email": "",
}, callback);

Get emails of the user (GET /user/emails)

ghme.emails(callback); //array of emails

Set emails of the user (POST /user/emails)

ghme.emails(['', ''], callback); //array of emails
ghme.emails('', callback); //array of emails

Delete emails of the user (DELETE /user/emails)

ghme.emails(['', '']);

Get the followers of the user (GET /user/followers)

ghme.followers(callback); //array of github users

Get users whom the user is following (GET /user/following)

ghme.following(callback); //array of github users

Check if the user is following a user (GET /user/following/marak)

ghme.following('marak', callback); //boolean

Follow a user (PUT /user/following/marak)


Unfollow a user (DELETE /user/following/marak)


Get public keys of a user (GET /user/keys)

ghme.keys(callback); //array of keys

Get a single public key (GET /user/keys/1)

ghme.keys(1, callback); //key

Create a public key (POST /user/keys)

ghme.keys({"title":"laptop", "key":"ssh-rsa AAA..."}, callback); //key

Update a public key (PATCH /user/keys/1)

ghme.keys(1, {"title":"desktop", "key":"ssh-rsa AAA..."}, callback); //key

Delete a public key (DELETE /user/keys/1)


List your public and private organizations (GET /user/orgs)

ghme.orgs(callback); // array of orgs

List your repositories (GET /user/repos)

ghme.repos(callback); //array of repos

Create a repository (POST /user/repos)

  "name": "Hello-World",
  "description": "This is your first repo",
}, callback); //repo

Fork a repository (POST /repos/pksunkara/hub/forks)

ghme.fork('pksunkara/hub', callback); //forked repo

Github users api

No token required for the following

Get information about an user (GET /users/pksunkara); //json

Get an user followers (GET /users/pksunkara/followers)

ghuser.followers(callback); //array of github users

Get an user followings (GET /users/pksunkara/following)

ghuser.following(callback); //array of github users

Github repositories api

Get information about a repository (GET /repos/pksunkara/octonode); //json

Get the commits for a repository (GET /repos/pkumar/hub/commits)

ghrepo.commits(callback); //array of commits

Get the tags for a repository (GET /repos/pksunkara/hub/tags)

ghrepo.tags(callback); //array of tags

Get the languages for a repository (GET /repos/pksunkara/hub/languages)

ghrepo.languages(callback); //array of languages

Get the contributors for a repository (GET /repos/pksunkara/hub/contributors)

ghrepo.contributors(callback); //array of github users

Get the branches for a repository (GET /repos/pksunkara/hub/branches)

ghrepo.branches(callback); //array of branches

Get the issues for a repository (GET /repos/pksunkara/hub/issues)

ghrepo.issues(callback); //array of issues

Get the README for a repository (GET /repos/pksunkara/hub/readme)

ghrepo.readme(callback); //file
ghrepo.readme('v0.1.0', callback); //file

Get the contents of a path in repository

ghrepo.contents('lib/index.js', callback); //path
ghrepo.contents('lib/index.js', 'v0.1.0', callback); //path

Get archive link for a repository

ghrepo.archive('tarball', callback); //link to archive
ghrepo.archive('zipball', 'v0.1.0', callback); //link to archive

Get the blob for a repository (GET /repos/pksunkara/hub/git/blobs/SHA)

ghrepo.blob('18293abcd72', callback); //blob

Get the teams for a repository (GET /repos/pksunkara/hub/teams)

ghrepo.teams(callback); //array of teams

Delete the repository (DELETE /repos/pksunkara/hub)


Github organizations api

Get information about an organization (GET /orgs/flatiron); //json

List organization repositories (GET /orgs/flatiron/repos)

ghorg.repos(callback); //array of repos

Create an organization repository (POST /orgs/flatiron/repos)

  name: 'Hello-world',
  description: 'My first world program'
}, callback); //repo

Get an organization's teams (GET /orgs/flatiron/teams)

ghorg.teams(callback); //array of teams

Get an organization's members (GET /orgs/flatiron/members)

ghorg.members(callback); //array of github users

Check an organization member (GET /orgs/flatiron/members/pksunkara)

ghorg.member('pksunkara', callback); //boolean

Github gists api

List authenticated user's gists (GET /gists)

ghgist.list(callback); //array of gists

List authenticated user's public gists (GET /gists/public)

ghgist.public(callback); //array of gists

List authenticated user's starred gists (GET /gists/starred)

ghgist.starred(callback); //array of gists

List a user's public gists (GET /users/pksunkara/gists)

ghgist.user('pksunkara', callback); //array of gists

Get a single gist (GET /gists/37)

ghgist.get(37, callback); //gist

Create a gist (POST /gists)

  description: "the description",
  files: { ... }
}), callback); //gist

Edit a gist (PATCH /gists/37)

ghgist.edit(37, {
  description: "hello gist"
}, callback); //gist

Delete a gist (DELETE /gists/37)


Star a gist (PUT /gists/37/star);

Unstar a gist (DELETE /gists/37/unstar)


Check if a gist is starred (GET /gists/37/star)

ghgist.check(37); //boolean

List comments on a gist (GET /gists/37/comments)

ghgist.comments(37, callback); //array of comments

Create a comment (POST /gists/37/comments)

ghgist.comments(37, {
  body: "Just commenting"
}, callback); //comment

Get a single comment (GET /gists/comments/1)

ghgist.comment(1, callback); //comment

Edit a comment (POST /gists/comments/1)

ghgist.comment(1, {
  body: "lol at commenting"
}, callback); //comment

Delete a comment (DELETE /gists/comments/1)


Github teams api

Get a team (GET /team/37); //json

Get the team members (GET /team/37/members)

ghteam.members(callback); //array of github users

Check if a user is part of the team (GET /team/37/members/pksunkara)

ghteam.member('pksunkara'); //boolean


npm test

If you like this project, please watch this and follow me.


Here is a list of Contributors


The following method names use underscore as an example. The library contains camel cased method names.

// public orgs for unauthenticated, private and public for authenticated

// public repos for unauthenticated, private and public for authenticated
me.is_watching('repo', callback);
me.start_watching('repo', callback);
me.stop_watching('repo', callback);
me.get_issues(params, callback);

// organization data
var org = octonode.Organization('bulletjs');

org.update(dict_with_update_properties, callback);
org.add_member('user', 'team', callback);
org.remove_member('user', callback);
org.is_public_member('user', callback);
org.make_member_public('user', callback);
org.conceal_member('user', callback);

org.get_team('team', callback);
org.create_team({name:'', repo_names:'', permission:''}, callback);
org.edit_team({name:'', permission:''}, callback);
org.delete_team('name', callback);
org.get_team_members('team', callback);
org.get_team_member('team', 'user', callback);
org.remove_member_from_team('user', 'team', callback);
org.create_repository({name: ''}, callback);
org.get_team_repositories('team', callback);
org.get_team_repository('team', 'name', callback);
org.add_team_repository('team', 'name', callback);
org.remove_team_repository('team', 'name', callback);

var repo = octonode.Repository('pksunkara/octonode');

repo.update({name: ''}, callback);

// collaborator information
repo.has_collaborator('name', callback);
repo.add_collaborator('name', callback);
repo.remove_collaborator('name', callback);

// commit data
repo.get_commit('sha-id', callback);
repo.get_commit_comments('SHA ID', callback);
repo.comment_on_commit({body: '', commit_id: '', line: '', path: '', position: ''}, callback);
repo.get_single_comment('comment id', callback);
repo.edit_single_comment('comment id', callback);
repo.delete_single_comment('comment id', callback);

// downloads
repo.create_download({name: ''}, 'filepath', callback);

// keys
repo.get_deploy_key('id', callback);
repo.create_deploy_key({title: '', key: ''}, callback);
repo.edit_deploy_key({title: '', key: ''}, callback);
repo.delete_deploy_key('id', callback);

// watcher data

// pull requests
repo.get_pull_request_comment('id', callback);
repo.create_pull_request_comment('id', {body:'', commit_id:'', path:'', position:''}, callback);
repo.reply_to_pull_request_comment('id', 'body', callback);
repo.edit_pull_request_comment('id', 'body', callback);
repo.delete_pull_request_comment('id', callback);
repo.get_issues(params, callback);
repo.get_issue('id', callback);
repo.create_issue({title: ''}, callback);
repo.edit_issue({title: ''}, callback);
repo.get_issue_comments('issue', callback);
repo.get_issue_comment('id', callback);
repo.create_issue_comment('id', 'comment', callback);
repo.edit_issue_comment('id', 'comment', callback);
repo.delete_issue_comment('id', callback);
repo.get_issue_events('id', callback);
repo.get_event('id', callback);
repo.get_label('id', callback);
repo.create_label('name', 'color', callback);
repo.edit_label('name', 'color', callback);
repo.delete_label('id', callback);
repo.get_issue_labels('issue', callback);
repo.add_labels_to_issue('issue', ['label1', 'label2'], callback);
repo.remove_label_from_issue('issue', 'labelid', callback);
repo.set_labels_for_issue('issue', ['label1', 'label2'], callback);
repo.remove_all_labels_from_issue('issue', callback);
repo.get_labels_for_milestone_issues('milestone', callback);
repo.get_milestone('id', callback);
repo.create_milestone('title', callback);
repo.edit_milestone('title', callback);
repo.delete_milestone('id', callback);

// raw git access
repo.create_blob('content', 'encoding', callback);
repo.get_commit('sha-id', callback);
repo.create_commit('message', 'tree', [parents], callback);
repo.get_reference('ref', callback);
repo.create_reference('ref', 'sha', callback);
repo.update_reference('ref', 'sha', force, callback);

I accept pull requests and guarantee a reply back within a day



Bug Reports

Report here. Guaranteed reply within a day.


Pavan Kumar Sunkara (

Follow me on github, twitter

Jump to Line
Something went wrong with that request. Please try again.