README.md

octonode

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

Installation

npm install octonode

Usage

var github = require('octonode');

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

var ghme           = client.me();
var ghuser         = client.user('pksunkara');
var ghrepo         = client.repo('pksunkara/hub');
var ghorg          = client.org('flatiron');
var ghissue        = client.issue('pksunkara/hub', 37);
var ghmilestone    = client.milestone('pksunkara/hub', 37);
var ghlabel        = client.label('pksunkara/hub', 'todo');
var ghpr           = client.pr('pksunkara/hub', 37);
var ghrelease      = client.release('pksunkara/hub', 37);
var ghgist         = client.gist();
var ghteam         = client.team(37);
var ghproject      = client.project('pksunkara/hub', 37);
var ghnotification = client.notification(37);

var ghsearch = client.search();

Build a client which accesses any public information

var client = github.client();

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

Build a client from an access token

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

client.get('/user', {}, function (err, status, body, headers) {
  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, headers) {
  console.log(body); //json object
});

Build a client from client keys

var client = github.client({
  id: 'abcdefghijklmno',
  secret: 'abcdefghijk'
});

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

Build a client from a different host

You can configure the protocol, hostname and port to use. For example to connect to a GitHub Enterprise instance.

var client = github.client({
  username: 'pksunkara',
  password: 'password'
},{
  hostname: 'mydomain.com/api/v3'
});

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

Request Options

Request options can be set by setting defaults on the client. (e.g. Proxies)

var client = github.client();

client.requestDefaults['proxy'] = 'https://myproxy.com:1085'

These options are passed through to request, see their API here: https://github.com/request/request#requestoptions-callback

Proxies

You can set proxies dynamically by using the example above, but Octonode will respect environment proxies by default. Just set this using: export HTTP_PROXY='https://myproxy.com:1085' if you are using the command line

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

Conditional requests

The client supports conditional requests and helps you respecting rate limits by caching information that hasn't changed. You can add the If-None-Match header to each request calling the conditional method.

var client = github.client();

// This add If-None-Match header to the request
github.repo().conditional('ETAG').issues();

More info about conditional requests can be founded here.

Authentication

Authenticate to github in cli mode (desktop application)

Note: Ensure that the scopes argument is an object containing the required note property. For two-factor authentication add the One Time Password otp key with its corresponding code to the configuration object.

var scopes = {
  'scopes': ['user', 'repo', 'gist'],
  'note': 'admin script'
};

github.auth.config({
  username: 'pksunkara',
  password: 'password'
}).login(scopes, function (err, id, token, headers) {
  console.log(id, token);
});

Revoke authentication to github in cli mode (desktop application)

github.auth.config({
  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',
  apiUrl: 'https://optional-internal-github-enterprise/api/v3',
  webUrl: 'https://optional-internal-github-enterprise'
}).login(['user', 'repo', 'gist']);

// Store info to verify against CSRF
var state = auth_url.match(/&state=([0-9a-z]{32})/i);

// Web server
http.createServer(function (req, res) {
  uri = url.parse(req.url);
  // Redirect to github login
  if (uri.pathname=='/login') {
    res.writeHead(302, {'Content-Type': 'text/plain', 'Location': auth_url})
    res.end('Redirecting to ' + auth_url);
  }
  // Callback url from github login
  else if (uri.pathname=='/auth') {
    var values = qs.parse(uri.query);
    // Check against CSRF attacks
    if (!state || state[1] != values.state) {
      res.writeHead(403, {'Content-Type': 'text/plain'});
      res.end('');
    } else {
      github.auth.login(values.code, function (err, token, headers) {
        res.writeHead(200, {'Content-Type': 'text/plain'});
        res.end(token);
      });
    }
  } else {
    res.writeHead(200, {'Content-Type': 'text/plain'})
    res.end('');
  }
}).listen(3000);

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

Rate Limiting

You can also check your rate limit status by calling the following.

client.limit(function (err, left, max, reset) {
  console.log(left); // 4999
  console.log(max);  // 5000
  console.log(reset);  // 1372700873 (UTC epoch seconds)
});

API Callback Structure

All the callbacks for the following will take first an error argument, then a data argument, like this:

ghme.info(function(err, data, headers) {
  console.log("error: " + err);
  console.log("data: " + data);
  console.log("headers:" + headers);
});

Async / Promises

If you would like to work with promises rather than callbacks, you can call the promise based version of any of the api calls by appending Async to the function call.

For example prs() becomes prsAsync() like this:

async function getPullRequests () {
  const client = github.client(config.githubAccessToken)
  const repo = client.repo('pksunkara/octonode')

  const result = await repo.prsAsync({ per_page: 100 })
  return result[0]
}

Pagination

If a function is said to be supporting pagination, then that function can be used in many ways as shown below. Results from the function are arranged in pages.

The page argument is optional and is used to specify which page of issues to retrieve. The perPage argument is also optional and is used to specify how many issues per page.

// Normal usage of function
ghrepo.issues(callback); //array of first 30 issues

// Using pagination parameters
ghrepo.issues(2, 100, callback); //array of second 100 issues
ghrepo.issues(10, callback); //array of 30 issues from page 10

// Pagination parameters can be set with query object too
ghrepo.issues({
  page: 2,
  per_page: 100,
  state: 'closed'
}, callback); //array of second 100 issues which are closed

Github authenticated user api

Token/Credentials required for the following:

Get information about the user (GET /user)

ghme.info(callback); //json

Update user profile (PATCH /user)

ghme.update({
  "name": "monalisa octocat",
  "email": "[email protected]",
}, 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(['[email protected]', '[email protected]'], callback); //array of emails
ghme.emails('[email protected]', callback); //array of emails

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

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

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)

This query supports pagination.

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)

ghme.follow('marak');

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

ghme.unfollow('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)

ghme.keys(1);

Get the starred repos for the user (GET /user/starred)

This query supports pagination.

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

Check if you have starred a repository (GET /user/starred/pksunkara/octonode)

ghme.checkStarred('flatiron/flatiron', callback); //boolean

Star a repository (PUT /user/starred/pksunkara/octonode)

ghme.star('flatiron/flatiron');

Unstar a repository (DELETE /user/starred/pksunkara/octonode)

ghme.unstar('flatiron/flatiron');

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

This query supports pagination.

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

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

This query supports pagination.

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

List your repositories (GET /user/repos)

This query supports pagination.

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

Create a repository (POST /user/repos)

ghme.repo({
  "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

List all issues across owned and member repositories (GET /user/issues)

This query supports pagination.

ghme.issues({
  page: 2,
  per_page: 100,
  filter: 'assigned',
  state: 'open',
  sort: 'created'
}, callback); //array of issues

List user teams (GET /user/teams)

This query supports pagination.

ghme.teams({
  page: 1,
  per_page: 50
}, callback); //array of team memberships

List notifications

Options based on http://git.io/vYYOx

ghme.notifications({}, callback); //array of notifications

Github users api

No token required for the following

Get information about a user (GET /users/pksunkara)

ghuser.info(callback); //json

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

This query supports pagination.

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

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

This query supports pagination.

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

Get user public repos (GET /users/pksunkara/repos)

This query supports pagination.

ghuser.repos(callback); //array of public github repos

Get events performed by a user (GET /users/pksunkara/events)

This query supports pagination.

Optionally, supply an array of Event Types to filter by.

ghuser.events(['PushEvent'], callback); //array of PushEvent events

Or leave it out to get all Event Types.

ghuser.events(callback); //array of events

Get user public organizations (GET /users/pksunkara/orgs)

This query supports pagination.

ghuser.orgs(callback); //array of organizations

Github repositories api

Get information about a repository (GET /repos/pksunkara/hub)

ghrepo.info(callback); //json

Edit a repository (PATCH /repos/pksunkara/hub)

ghrepo.update({
  private: false
}, callback); // repo

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

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

Check if a user is collaborator for a repository (GET /repos/pksunkara/hub/collaborators/marak)

ghrepo.collaborators('marak', callback); //boolean

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

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

Get a certain commit for a repository (GET /repos/pksunkara/hub/commits/18293abcd72)

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

Get a comparison between branches for a repository (GET /repos/pksunkara/hub/compare/master...develop)

ghrepo.compare('master', 'develop', callback); //compare develop to master

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

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

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

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

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)

This query supports pagination.

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

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

ghrepo.branch('master', callback); //branch

Create a Reference (POST /repos/pksunkara/hub/git/refs)

ghrepo.createReference('master', '18293abcd72', callback);

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

This query supports pagination.

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

Create an issue for a repository (POST /repos/pksunkara/hub/issues)

ghrepo.issue({
  "title": "Found a bug",
  "body": "I'm having a problem with this.",
  "assignee": "octocat",
  "milestone": 1,
  "labels": ["Label1", "Label2"]
}, callback); //issue

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

This query supports pagination.

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

Create a milestone for a repository (POST /repos/pksunkara/hub/milestones)

ghrepo.milestone({
  "title": "Sprint 345",
  "description": "The sprint where we fix all the things!",
  "due_on": new Date(2014, 7, 1)
}, callback); //milestone

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

This query supports pagination.

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

Create a project for a repository (POST /repos/pksunkara/hub/projects)

ghrepo.project({
  "name": "Sprint 345",
  "body": "The sprint where we fix all the things!"
}, callback); //project

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

This query supports pagination.

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

Create a label for a repository (POST /repos/pksunkara/hub/labels)

ghrepo.label({
  "name": "Priority",
  "color": "ff0000",
}, callback); //label

Get the pull requests for a repository (GET /repos/pksunkara/hub/pulls)

This query supports pagination.

ghrepo.prs(callback); //array of pull requests

Create a pull request (POST /repos/pksunkara/hub/pulls)

ghrepo.pr({
  "title": "Amazing new feature",
  "body": "Please pull this in!",
  "head": "octocat:new-feature",
  "base": "master"
}, callback); //pull request

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

This query supports pagination.

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

Create a hook (POST /repos/pksunkara/hub/hooks)

ghrepo.hook({
  "name": "web",
  "active": true,
  "events": ["push", "pull_request"],
  "config": {
    "url": "http://myawesomesite.com/github/events"
  }
}, callback); // hook

Delete a hook (DELETE /repos/pksunkara/hub/hooks/37)

ghrepo.deleteHook(37, callback);

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

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

Get the root contents on a branch called "myBranch"

ghrepo.contents('', "myBranch", callback);

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

Create a file at a path in repository

ghrepo.createContents('lib/index.js', 'commit message', 'content', callback); //path
ghrepo.createContents('lib/index.js', 'commit message', 'content', 'v0.1.0', callback); //path

Update a file at a path in repository

ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', callback); //path
ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', 'master', callback); //path
ghrepo.updateContents('lib/index.js', 'commit message', 'content', 'put-sha-here', 'v0.1.0', callback); //path

Delete a file at a path in repository

ghrepo.deleteContents('lib/index.js', 'commit message', 'put-sha-here', callback); //path
ghrepo.deleteContents('lib/index.js', 'commit message', 'put-sha-here', '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 users who starred a repository (GET /repos/pksunkara/hub/stargazers)

ghrepo.stargazers(1, 100, callback); //array of users
ghrepo.stargazers(10, callback);     //array of users
ghrepo.stargazers(callback);         //array of users

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

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

Get a git tree (GET /repos/pksunkara/hub/git/trees/18293abcd72)

ghrepo.tree('18293abcd72', callback); //tree
ghrepo.tree('18293abcd72', true, callback); //recursive tree

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

ghrepo.destroy();

List statuses for a specific ref (GET /repos/pksunkara/hub/statuses/master)

ghrepo.statuses('master', callback); //array of statuses

List the combined status for a specific ref (GET /repos/pksunkara/hub/commits/master/status)

ghrepo.combinedStatus('master', callback); //array of statuses

Create status (POST /repos/pksunkara/hub/statuses/SHA)

ghrepo.status('18e129c213848c7f239b93fe5c67971a64f183ff', {
  "state": "success",
  "target_url": "http://ci.mycompany.com/job/hub/3",
  "description": "Build success."
}, callback); // created status

GitHub notifications api

Mark a thread as read

ghnotification.markAsRead(callback);

Subscribe to a thread

ghnotification.subscribe(callback);

Unsubscribe from a thread

ghnotification.unsubscribe(callback);

Mute a thread

ghnotification.mute(callback);

Github organizations api

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

ghorg.info(callback); //json

Update an organization (POST /orgs/flatiron)

ghorg.update({
  blog: 'https://blog.com'
}, callback); // org

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

This query supports pagination.

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

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

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

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

This query supports pagination.

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

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

This query supports pagination.

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

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

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

Check a member's public membership in an org (GET /orgs/flatiron/public_members/pksunkara)

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

Publicize a user’s membership (PUT /orgs/flatiron/public_members/pksunkara)

ghorg.publicizeMembership('pksunkara', callback);

Conceal a user’s membership (DELETE /orgs/flatiron/public_members/pksunkara)

ghorg.concealMembership('pksunkara', callback);

Check a member's membership status (GET /orgs/flatiron/memberships/pksunkara)

ghorg.membership('pksunkara', callback); //membership status object indicating state, role, etc.

Create an organization team (POST /orgs/flatiron/teams)

ghorg.createTeam({
  "name": "new team name",
  "permission": "push",
  "repo_names": [
    "flatiron/utile"
   ]
}, callback);

Get the hooks for a Organization (GET /orgs/flatiron/hooks)

This query supports pagination.

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

Create a hook (POST /orgs/flatiron/hooks)

ghorg.hook({
  "name": "web",
  "active": true,
  "events": ["push", "pull_request"],
  "config": {
    "url": "http://myawesomesite.com/github/events"
  }
}, callback); // hook

Delete a hook (DELETE /orgs/flatiron/hooks/37)

ghorg.deleteHook(37, callback);

Github issues api

Get a single issue (GET /repos/pksunkara/hub/issues/37)

ghissue.info(callback); //issue

Edit an issue for a repository (PATCH /repos/pksunkara/hub/issues/37)

ghissue.update({
  "title": "Found a bug and I am serious",
}, callback); //issue

List comments on an issue (GET /repos/pksunkara/hub/issues/37/comments)

This query supports pagination.

ghissue.comments(callback); //array of comments

Create a comment (POST /repos/pksunkara/hub/issues/37/comments)

ghissue.createComment({
  body: 'Me too.'
}, callback);

Edit a comment (PATCH /repos/pksunkara/hub/issues/comments/3)

ghissue.updateComment(3, {
  body: 'The updated body of the comment.'
}, callback);

Delete a comment (DELETE /repos/pksunkara/hub/issues/comments/3)

ghissue.deleteComment(3, callback);

List labels on an issue (GET /repos/pksunkara/hub/issues/37/labels)

ghissue.labels(callback);

Add label(s) (POST /repos/pksunkara/hub/issues/37/labels)

ghissue.addLabels(['label-name'], callback);

Replace all labels (PUT /repos/pksunkara/hub/issues/37/labels)

ghissue.replaceAllLabels(['label-name'], callback);

Remove a single label (DELETE /repos/pksunkara/hub/issues/37/labels/label-name)

ghissue.removeLabel('label-name', callback);

Remove all labels (DELETE /repos/pksunkara/hub/issues/37/labels)

ghissue.removeAllLabels(callback);

Github milestones api

Get a single milestone (GET /repos/pksunkara/hub/milestones/37)

ghmilestone.info(callback); //milestone

Edit a milestone for a repository (PATCH /repos/pksunkara/hub/milestones/37)

ghmilestone.update({
  "title": "Updated milestone title",
}, callback); //milestone

Delete a milestone for a repository (DELETE /repos/pksunkara/hub/milestones/37)

ghmilestone.delete(callback); //milestone

Github projects api

Get a single project (GET /repos/pksunkara/hub/projects/37)

ghproject.info(callback); //project

Edit a project for a repository (PATCH /repos/pksunkara/hub/projects/37)

ghproject.update({
  "name": "Updated project name",
}, callback); //project

Delete a project for a repository (DELETE /repos/pksunkara/hub/projects/37)

ghproject.delete(callback); //project

Github labels api

Get a single label (GET /repos/pksunkara/hub/labels/todo)

ghlabel.info(callback); //label

Edit a label for a repository (PATCH /repos/pksunkara/hub/labels/todo)

ghlabel.update({
  "color": "000000",
}, callback); //label

Delete a label for a repository (PATCH /repos/pksunkara/hub/labels/todo)

ghlabel.delete(callback); //label

Github Merge API

Merge a branch (POST /repose/pksunkara/hub/merges)

ghrepo.merge({ base: baseBranch, head: destinationBranch }, callback);

Github pull requests api

Get a single pull request (GET /repos/pksunkara/hub/pulls/37)

ghpr.info(callback); //pull request

Update a pull request (PATCH /repos/pksunkara/hub/pulls/37)

ghpr.update({
  'title': 'Wow this pr'
}, callback); //pull request

Close a pull request

ghpr.close(callback); //pull request

Get if a pull request has been merged (GET /repos/pksunkara/hub/pulls/37/merge)

ghpr.merged(callback); //boolean

List commits on a pull request (GET /repos/pksunkara/hub/pulls/37/commits)

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

List comments on a pull request (GET /repos/pksunkara/hub/pulls/37/comments)

ghpr.comments(callback); //array of comments

Add a comment on a pull request (POST /repos/pksunkara/hub/pulls/37/comments)

ghpr.createComment({
  body: 'my comment',
  commit_id: '8cde3b6c5be2c3067cd87ee4117c0f65e30f3e1f', // needed to comment on current time in PR
  path: 'file.txt', // optional
  position: 4 // optional
}, callback);

Remove a comment on a pull request (DELETE /repos/pksunkara/hub/pulls/37/comments/104)

ghpr.removecomment(104, callback);

List files in pull request (GET /repos/pksunkara/hub/pulls/37/files)

ghpr.files(callback); //array of files

List pull request reviews (GET /repos/pksunkara/hub/pulls/37/reviews)

ghpr.reviews(callback); //array of pull request reviews

Get a single pull request review (GET /repos/pksunkara/hub/pulls/37/reviews/104)

ghpr.review(104, callback); //pull request review

Delete a pending pull request review (DELETE /repos/pksunkara/hub/pulls/37/reviews/104)

ghpr.removeReview(104, callback); //pull request review

List comments for a pull request review (GET /repos/pksunkara/hub/pulls/37/reviews/104/comments)

ghpr.reviewComments(104, callback); //array of review comments

Create a pull request review (POST /repos/pksunkara/hub/pulls/37/reviews)

ghpr.createReview({
  body: 'review message', // optional
  comments: [ // optional
    {
      body: 'comment message', // required for each optional comment
      path: 'file.txt', // required for each optional comment
      position: 4 // required for each optional comment
    }
  ],
  event: 'APPROVE || COMMENT || REQUEST_CHANGES' // optional
}, callback); //pull request review

Submit a pull request review (POST /repos/pksunkara/hub/pulls/37/reviews/104/events)

ghpr.submitReview(104, {
  body: 'review message', // optional
  event: 'APPROVE || COMMENT || REQUEST_CHANGES' // required
}, callback); //pull request review

Dismiss a pull request review (PUT /repos/pksunkara/hub/pulls/37/reviews/104/dismissals)

ghpr.dismissReview(104, 'dismissal message', callback); //pull request review

List review requests (GET /repos/pksunkara/hub/pulls/37/requested_reviewers)

ghpr.reviewRequests(callback); //array of review requests

Create review request(s) (POST /repos/pksunkara/hub/pulls/37/requested_reviewers)

ghpr.createReviewRequests(['user1', 'user2'], callback); //pull request

Delete review request(s) (DELETE /repos/pksunkara/hub/pulls/37/requested_reviewers)

ghpr.removeReviewRequests(['user1', 'user2'], callback); //pull request

Github releases api

Create release (POST /repos/pksunkara/releases)

ghrepo.release({
  tag_name: 'v1.0.0',
  draft: true
}, callback);

Upload assets in a release (POST /uploads.github.com/repos/pksunkara/hub/releases/37/assets?name=archve-v0.0.1.zip)

var archive = fs.readFileSync(__dirname, 'archive-v0.0.1.zip');
// Will upload a file with the default options
/*
{
  name: 'archive.zip',
  contentType: 'application/zip',
  uploadHost: 'uploads.github.com'
}
*/
ghrelease.uploadAssets(archive, callback);

// Will upload a file with your custom options
var image = fs.readFileSync(__dirname, 'octonode.png');
var options = {
  name: 'octonode.png',
  contentType: 'image/png',
  uploadHost: 'uploads.github.com'
};
ghrelease.uplaodAssets(image, options, callback)

Github gists api

List authenticated user's gists (GET /gists)

This query supports pagination.

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

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

This query supports pagination.

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

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

This query supports pagination.

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

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

This query supports pagination.

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

Get a single gist (GET /gists/37)

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

Create a gist (POST /gists)

ghgist.create({
  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)

ghgist.delete(37);

Fork a gist (POST /gists/37/forks)

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

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

ghgist.star(37);

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

ghgist.unstar(37);

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)

ghgist.comment(1);

Github teams api

Get a team (GET /team/37)

ghteam.info(callback); //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', callback); //boolean

Add a user to a team (PUT /team/37/members/pksunkara)

ghteam.addUser("pksunkara", callback); //boolean

Remove a user from a team (DELETE /team/37/members/pksunkara)

ghteam.removeUser("pksunkara", callback); //boolean

Get team membership (GET /teams/37/memberships/pksunkara)

ghteam.membership("pksunkara", callback); //boolean

Add team membership (PUT /teams/37/memberships/pksunkara)

ghteam.addMembership("pksunkara", callback); //boolean

Remove team membership (DELETE /team/37/memberships/pksunkara)

ghteam.removeMembership("pksunkara", callback); //boolean

List all repos of a team (GET /team/37/repos)

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

Remove a repo from a team (DELETE /team/37/repos/flatiron/hub)

ghteam.removeRepo("flatiron/hub", callback);

Delete a team (DELETE /team/37)

ghteam.destroy(callback);

Github search api

Search issues

ghsearch.issues({
  q: 'windows+state:open+repo:pksunkara/hub',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

Search repositories

ghsearch.repos({
  q: 'hub+language:go',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

Search users

ghsearch.users({
  q: 'tom+followers:>100',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

Search code

ghsearch.code({
  q: 'auth+in:file+repo:pksunkara/hub',
  sort: 'created',
  order: 'asc'
}, callback); //array of search results

Get all Organizations / Users

This query supports pagination.

Note: For listing all Organizations / Users pagination is powered exclusively by the since parameter ( Github APIs ) . since denotes the login ID of last org / user you encountered. Also, note that it's important to pass true as third param when using pagination.

Organizations

  var client = github.client();
  client.get('/organizations', callback);
  // OR
  client.get('/organizations', since, per_page, true, callback);

Users

  var client = github.client();
  client.get('/users', callback);
  // OR
  client.get('/users', since, per_page, true, callback);

Testing

Before run test copy the config.example.json file in test folder to config.json and populate it with your github information.

Is suggested to fork https://github.com/octocat/Spoon-Knife repo and run test on your copy.

npm test

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

Contributors

Here is a list of Contributors

TODO

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

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

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

org.update(dict_with_update_properties, callback);
org.get_public_members(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.get_repositories(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.add_collaborator('name', callback);
repo.remove_collaborator('name', callback);

// commit data
repo.get_commit('sha-id', callback);
repo.get_all_comments(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.get_downloads(callback);
repo.get_download(callback);
repo.create_download({name: ''}, 'filepath', callback);
repo.delete_download(callback);

// keys
repo.get_deploy_keys(callback);
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
repo.get_watchers(callback);

// pull requests
repo.get_all_pull_request_comments(callback);
repo.get_pull_request_comment('id', callback);
repo.reply_to_pull_request_comment('id', 'body', callback);
repo.edit_pull_request_comment('id', 'body', 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_events(callback);
repo.get_event('id', callback);
repo.get_labels(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_labels_for_milestone_issues('milestone', callback);
repo.get_milestones(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.get_all_references(callback);
repo.update_reference('ref', 'sha', force, callback);

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

License

MIT/X11

Bug Reports

Report here. Guaranteed reply within a day.

Contact

Pavan Kumar Sunkara ([email protected])

Follow me on github, twitter