A Hubot-compatible Github API wrapper for Node.js
Install
npm install githubot
Require
Use it in your Hubot script:
= github = require'githubot'robot
Or use it on its own:
github = require'githubot'
You can pass additional options to the constructor if needed.
Use
Make any call to the Github v3 API, get the parsed JSON response:
githubget "https://api.github.com/users/iangreenleaf/gists" consolelog gists0description githubget "users/foo/repos"type: "owner" consolelog repos0url data = description: "A test gist"public: truefiles: "abc.txt": content: "abcdefg" githubpost "gists"data consolelog gisturl githubpatch "repos/my/repo/issues/11"status: "closed" consolelog issuehtml_url
Authentication
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 https://api.github.com/authorizations -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:
githubhandleErrors consolelog "Oh no! !"
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:
githubqualified_repo "githubot" # => "iangreenleaf/githubot"
This will happen with the bespoke methods as well:
ghbranches "githubot"
Options
Passing options
Options may be passed to githubot in three different ways, in increasing order of precedence:
-
Through shell environment variables.
-
Through the constructor:
github = require'githubot'robotapiVersion: 'preview' -
Using
withOptions
, which lets you pass options to only some requests:github = require'githubot'robotpreview = githubwithOptionsapiVersion: 'preview'# Uses preview APIpreviewget '/preview/feature'-> # ...# Uses regular APIgithubget '/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='https://myprivate.github.int'
-
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:
Branches
List branches
ghbranches "foo/bar" consolelog branches0name
Create a branch
# Branch from master ghbranches "foo/bar" create "my_radical_feature" consolelog branchsha # Branch from another branch ghbranches "foo/bar" create "even_more_radical"from: "my_radical_feature" consolelog branchsha
Merge a branch
# Merge a branch into master ghbranches "foo/bar" merge "my_radical_feature" consolelog mergeCommitmessage # Merge a branch into a different target ghbranches "foo/bar" merge "my_radical_feature"into: "hotfixes" consolelog mergeCommitmessage # `base` is an alias for `into` ghbranches "foo/bar" merge "my_radical_feature"base: "hotfixes" consolelog mergeCommitmessage # Provide your own commit message ghbranches "foo/bar" merge "my_radical_feature"message: "Merge my radical feature!" consolelog mergeCommitsha
Delete a branch
ghbranches "foo/bar" delete "my_radical_feature"-> consolelog "Deleted my branch!"
Deployments
Note: These methods are smart and automatically use the
cannonball-preview
version header. No intervention needed!
List deployments
ghdeployments "foo/bar" consolelog deployslength
Create a deployment
ghdeployments"foo/bar" create 'my-branch'payload: env: 'staging'description: "Ship it!" consolelog deployurl
Deployment statuses
ghdeployments"foo/bar"status deployId consolelog deploys0state
Contributing
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.