Hubot-compatible Github API wrapper for Node.js
Last updated 4 years ago by iangreenleaf .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install githubot 
SYNC missed versions from official npm registry.

A Hubot-compatible Github API wrapper for Node.js

Build Status


npm install githubot


Use it in your Hubot script:

module.exports = (robot) ->
  github = require('githubot')(robot)

Or use it on its own:

github = require('githubot')

You can pass additional options to the constructor if needed.


Make any call to the Github v3 API, get the parsed JSON response:

github.get "", (gists) ->
  console.log gists[0].description

github.get "users/foo/repos", {type: "owner"}, (repos) ->
  console.log repos[0].url

data = { description: "A test gist", public: true, files: { "abc.txt": { content: "abcdefg" } } } "gists", data, (gist) ->
  console.log gist.url

github.patch "repos/my/repo/issues/11", {status: "closed"}, (issue) ->
  console.log issue.html_url


If process.env.HUBOT_GITHUB_TOKEN is present, you're automatically authenticated. Sweet!

Acquire a token

If you don't have a token yet, run this:

curl -i -d '{"note":"githubot","scopes":["repo"]}' -u "yourusername"

Enter your Github password when prompted. When you get a response, look for the "token" value.

If you have two-factor authentication enabled, you'll have to append -H 'X-GitHub-OTP: 123456' to the end of the above command, or you'll receive HTTP 401 Unauthorized instead of your token.

Handling errors

GitHubot will log errors automatically if it has a logger. Used with Hubot, these will go to the Hubot logger.

If your script would like to catch errors as well, define an extra callback:

github.handleErrors (response) ->
  console.log "Oh no! #{response.statusCode}!"

The callback takes a response argument with the following keys:

  • error: The error message.
  • statusCode: The status code of the API response, if present.
  • body: The body of the API response, if present.

You can also pass an error handler in the options instead.

Helpful Hubot

If process.env.HUBOT_GITHUB_USER is present, we can help you guess a repo's full name:

github.qualified_repo "githubot" # => "iangreenleaf/githubot"

This will happen with the bespoke methods as well:

gh.branches "githubot", (branches) ->


Passing options

Options may be passed to githubot in three different ways, in increasing order of precedence:

  1. Through shell environment variables.

  2. Through the constructor:

    github = require('githubot')(robot, apiVersion: 'preview')
  3. Using withOptions, which lets you pass options to only some requests:

    github = require('githubot')(robot)
    preview = github.withOptions(apiVersion: 'preview')
    # Uses preview API
    preview.get '/preview/feature', -> # ...
    # Uses regular API
    github.get '/regular/feature', -> # ...

Available options

  • token/process.env.HUBOT_GITHUB_TOKEN: GitHub API token. Required to perform authenticated actions.

  • apiVersion/process.env.HUBOT_GITHUB_API_VERSION: Version of the API to access. Defaults to 'v3'.

  • defaultUser/process.env.HUBOT_GITHUB_USER: Default GitHub username to use if one is not given.

  • apiRoot/process.env.HUBOT_GITHUB_API: The base API URL. This is useful for Enterprise Github installations.

    For example, HUBOT_GITHUB_API=''

  • concurrentRequests/process.env.HUBOT_CONCURRENT_REQUESTS: Limits the allowed number of concurrent requests to the GitHub API. Defaults to 20.

  • errorHandler: Function for custom error handling logic. See handling errors for more details.

Bespoke API access

Mostly a work in progress, but here's a taste of what I have in mind:


List branches

gh.branches "foo/bar", (branches) ->
  console.log branches[0].name

Create a branch

# Branch from master
gh.branches( "foo/bar" ).create "my_radical_feature", (branch) ->
  console.log branch.sha

# Branch from another branch
gh.branches( "foo/bar" ).create "even_more_radical", from: "my_radical_feature", (branch) ->
  console.log branch.sha

Merge a branch

# Merge a branch into master
gh.branches( "foo/bar" ).merge "my_radical_feature", (mergeCommit) ->
  console.log mergeCommit.message

# Merge a branch into a different target
gh.branches( "foo/bar" ).merge "my_radical_feature", into: "hotfixes", (mergeCommit) ->
  console.log mergeCommit.message

# `base` is an alias for `into`
gh.branches( "foo/bar" ).merge "my_radical_feature", base: "hotfixes", (mergeCommit) ->
  console.log mergeCommit.message

# Provide your own commit message
gh.branches( "foo/bar" ).merge "my_radical_feature", message: "Merge my radical feature!", (mergeCommit) ->
  console.log mergeCommit.sha

Delete a branch

gh.branches( "foo/bar" ).delete "my_radical_feature", ->
  console.log "Deleted my branch!"


Note: These methods are smart and automatically use the cannonball-preview version header. No intervention needed!

List deployments

gh.deployments "foo/bar", (deploys) ->
  console.log deploys.length

Create a deployment

  .create 'my-branch', payload: {env: 'staging'}, description: "Ship it!", (deploy) =>
    console.log deploy.url

Deployment statuses

gh.deployments("foo/bar").status deployId, (deploys) ->
  console.log deploys[0].state


Install the dependencies:

npm install

Run the tests:

make test
make test-all # Runs additional slower "integration" style tests, generally not necessary

Pull requests encouraged!

I'm vastly more likely to merge code that comes with tests. If you're confused by the testing process, ask and I can probably point you in the right direction.


These lovely people have contributed to githubot.

Current Tags

  • 1.0.1                                ...           latest (4 years ago)

18 Versions

  • 1.0.1                                ...           4 years ago
  • 1.0.0                                ...           5 years ago
  • 1.0.0-beta2                                ...           6 years ago
  • 0.5.0                                ...           6 years ago
  • 0.4.2                                ...           7 years ago
  • 0.4.1                                ...           7 years ago
  • 0.4.0                                ...           7 years ago
  • 0.3.1                                ...           7 years ago
  • 0.3.0                                ...           8 years ago
  • 0.2.1                                ...           8 years ago
  • 0.2.0                                ...           8 years ago
  • 0.1.6                                ...           8 years ago
  • 0.1.5                                ...           8 years ago
  • 0.1.4                                ...           8 years ago
  • 0.1.3                                ...           8 years ago
  • 0.1.2                                ...           8 years ago
  • 0.1.1                                ...           8 years ago
  • 0.1.0                                ...           8 years ago

Copyright 2014 - 2016 © |