octokit

What is octokit?

The octokit npm package is a comprehensive toolkit for interacting with the GitHub API. It allows developers to perform a wide range of actions such as managing repositories, issues, pull requests, and more. Octokit is designed to be flexible and powerful, making it easier to integrate GitHub functionalities into applications.

What are octokit's main functionalities?

Repository Management

This feature allows you to manage repositories, including creating new ones. The code sample demonstrates how to create a new repository for the authenticated user.

const { Octokit } = require('@octokit/rest');
const octokit = new Octokit({ auth: 'your-token-here' });

async function createRepo() {
  const response = await octokit.repos.createForAuthenticatedUser({
    name: 'new-repo',
    private: false
  });
  console.log(response.data);
}

createRepo();

Issue Management

This feature allows you to manage issues, including creating new ones. The code sample demonstrates how to create a new issue in a specified repository.

const { Octokit } = require('@octokit/rest');
const octokit = new Octokit({ auth: 'your-token-here' });

async function createIssue() {
  const response = await octokit.issues.create({
    owner: 'your-username',
    repo: 'your-repo',
    title: 'New Issue',
    body: 'Issue description here'
  });
  console.log(response.data);
}

createIssue();

Pull Request Management

This feature allows you to manage pull requests, including creating new ones. The code sample demonstrates how to create a new pull request in a specified repository.

const { Octokit } = require('@octokit/rest');
const octokit = new Octokit({ auth: 'your-token-here' });

async function createPullRequest() {
  const response = await octokit.pulls.create({
    owner: 'your-username',
    repo: 'your-repo',
    title: 'New Pull Request',
    head: 'branch-name',
    base: 'main',
    body: 'Pull request description here'
  });
  console.log(response.data);
}

createPullRequest();

Other packages similar to octokit

node-github

The node-github package is another library for interacting with the GitHub API. It offers similar functionalities to octokit, such as managing repositories, issues, and pull requests. However, octokit is generally more up-to-date and better maintained.

github-api

The github-api package provides a simple interface for interacting with the GitHub API. While it offers similar functionalities to octokit, it is less comprehensive and may lack some of the advanced features and flexibility that octokit provides.

gh.js

The gh.js package is a lightweight library for interacting with the GitHub API. It is designed to be simple and easy to use, but it may not offer the same level of functionality and customization as octokit.

README

octokit.js

octokit.js provides a minimal higher-level wrapper around git's plumbing commands, exposing an API for manipulating GitHub repositories, users, groups, and gists. It is being developed in the context of github-bookeditor, an EPUB3 editor for GitHub.

This package can also be used in nodejs or as an AMD module in the browser.

Key Features

• Works in nodejs, a AMD module in the browser, a bower library
• Simple read and write methods for text and binary files
• Creating gists, Pull Requests, forks, and new Repositories
• ETag Caching
• Promises instead of callbacks (for better error-handling and progress updating)
• Progress Notifications for multistep operations
• Starring and Following repositories, users, and organizations
• Editing Team and Organization Membership
• User/Org/Repo events and notifications
• Listeners for rate limit changes
• Public Keys
• Hooks (commit, comment, etc)

Usage

All asynchronous methods return a Common-JS Promise. See jQuery.Deferred or Node's Q for more information.

In a browser without requirejs

Create an Octokit instance.

var gh = new Octokit({
  username: "YOU_USER",
  password: "YOUR_PASSWORD"
});

Or if you prefer OAuth, it looks like this:

var gh = new Octokit({
  token: "OAUTH_TOKEN"
});

In a browser using requirejs

define(['octokit'], function(Octokit) {
  var gh = new Octokit({
    username: "YOU_USER",
    password: "YOUR_PASSWORD"
  });
});

In Nodejs

Install instructions:

npm install octokit --save

var Octokit = require('octokit');
var gh = Octokit.new({
  username: "YOU_USER",
  password: "YOUR_PASSWORD"
});

Using bower

This file can be included using the bower package manager:

bower install octokit --save

Development

Mocha tests are run on NodeJS by running npm test. Mocha tests in the browser and code coverage are run by going to ./test/index.html.

Repository API

var repo = gh.getRepo(username, reponame);

Show repository information

repo.getInfo()
.done(function(repo) {})
.fail(function(err) {});

List all branches in a Repository

repo.getBranches()
.done(function(branches) {});

Fork a repository

repo.fork()
.done(function() {});

Create a Pull Request

repo.createPullRequest()
.done(function() {});

Get recent commits to the repository

var options = {};
repo.getCommits(options)
.done(function(commits) {});

List Repository events

repo.getEvents()
.done(function(events) {});

List Issue events for the repository

repo.getIssueEvents()
.done(function(events) {});

List events for a network of Repositories

repo.getNetworkEvents()
.done(function(events) {});

List unread notifications for authenticated user pertaining to this repository

var options = {};
repo.getNotifications(options)
.done(function(events) {});

Get programming language counts (CoffeeScript, Ruby, Shell)

repo.getLanguages()
.done(function(events) {});

Branch API

Additional methods are available for a specific branch in a repository

Get the Default branch of a repository

var branch = repo.getDefaultBranch();

Get a specific branch of a repository

var branch = repo.getBranch("BRANCH_NAME");

Read a file from the branch

var isBinary = false;
branch.read('PATH/TO/FILE.txt', isBinary)
.done(function(contents) {})
.fail(function(err) {});

Remove a file from the branch

var message = "OPTIONAL COMMIT MESSAGE";
branch.remove('PATH/TO/FILE.txt', message)
.done(function() {});

Read the contents (raw) of a file or directory

branch.contents('DIRECTORY/PATH')
.done(function(contents) {});

or

branch.contents('DIRECTORY/PATH/FILE.txt')
.done(function(contents) {});

Move a file

var message = "OPTIONAL COMMIT MESSAGE";
branch.move('PATH/TO/FILE.txt', 'NEW/PATH/TO/FILE.txt', message)
.done(function() {});

Write a file (update or add)

var content = "Contents of the file";
var message = "OPTIONAL COMMIT MESSAGE";
var isBinary = false;
branch.write('PATH/TO/FILE.txt', content, message, isBinary)
.done(function() {});

Write multiple files (update or add) in one commit

var contents = {
  "FILE1.txt": "Contents of the file",
  "FILE2.txt": {isBase64: true, content: "BASE_64_ENCODED_STRING"}
}
branch.write(contents, message)
.done(function() {});

Get recent commits to a branch

var options = {};
branch.getCommits(options)
.done(function(commits) {});

Create a new branch

branch.createBranch("new-branch-name")
.done(function() {});

Low-level Repo API

The methods on a branch or repo use the following low-level methods.

repo.git.getRef(...)      .done(function(result) {});
repo.git.createRef(...)   .done(function(result) {});
repo.git.deleteRef(...)   .done(function(result) {});
repo.git.getBranches()    .done(function(result) {});
repo.git.getBlob(...)     .done(function(result) {});
repo.git.getSha(...)      .done(function(result) {});
repo.git.getTree(...)     .done(function(result) {});
repo.git.postBlob(...)    .done(function(result) {});
repo.git.updateTree(...)  .done(function(result) {});
repo.git.postTree(...)    .done(function(result) {});
repo.git.commit(...)      .done(function(result) {});
repo.git.updateHead(...)  .done(function(result) {});
repo.git.getCommits(...)  .done(function(result) {});

User API

var user = gh.getUser("ANY_GITHUB_USERNAME");

Show user information for a particular user. Also works for organizations.

user.getInfo()
.done(function(user) {})
.fail(function(err) {});

List public repositories for a particular user.
options described here

user.getRepos(type='all', sort='pushed', direction='desc')
.done(function(repos) {});

List organizations the user is in.

user.getOrgs()
.done(function(orgs) {});

List all gists of a particular user.

user.getGists()
.done(function(gists) {});

List users following this user.

user.getFollowers()
.done(function(users) {});

List users this user is following.

user.getFollowing()
.done(function(users) {});

Get Received events for this user.

user.getReceivedEvents()
.done(function(events) {});

Get all events for this user.

user.getEvents()
.done(function(events) {});

Authenticated User API

The Authenticated User contains the following methods in addition to all the methods in the User API.

Get the authenticated user.

var user = gh.getUser();

List unread notifications for the user.

gh.getNotifications()
.done(function(notifications) {})
.fail(function(err) {});

List private and public repositories of the current authenticated user.

user.getRepos()
.done(function(repos) {});

Follow another user.

var username "SOME_OTHER_USERNAME";
user.follow(username)
.done(function(orgs) {});

Stop following another user.

var username "SOME_OTHER_USERNAME";
user.unfollow(username)
.done(function(orgs) {});

Gist API

var gist = gh.getGist(3165654);

Read the contents of a Gist.

gist.read()
.done(function(gist) {});

Update the contents of a Gist. Please consult the documentation on GitHub.

var delta = {
  "description": "the description for this gist",
  "files": {
    "file1.txt": {
      "content": "updated file contents"
    },
    "old_name.txt": {
      "filename": "new_name.txt",
      "content": "modified contents"
    },
    "new_file.txt": {
      "content": "a new file"
    },
    "delete_this_file.txt": null
  }
};

gist.update(delta)
.done(function(gist) {});

Create a Gist

var files = {
  'file1.txt': {content: 'String file contents'}
};

gh.getGist().create(files)
.done(function(gist) {});

Delete the Gist

gist.delete()
.done(function(gist) {});

Fork the Gist

gist.fork()
.done(function(gist) {});

Star the Gist

gist.star()
.done(function() {});

Unstar the Gist

gist.unstar()
.done(function() {});

Check if the Gist is starred

gist.isStarred()
.done(function() {});

Miscellaneous methods

Retreive a zen message (to test the API works).

gh.getZen()
.done(function(msg) {})
.fail(function(err) {});

Add a listener for rateLimit changes

function listener(rateLimitRemaining, rateLimit, method, path, data, raw, isBase64) {
  // ...
};
gh.onRateLimitChanged(listener);

List repositories for a particular organization. Includes private repositories if you are authorized.

gh.getOrgRepos(orgname)
.done(function(repos) {});

Progress Notifications

For multistep operations users can listen to updates by registering a listener at promise.progress(function(obj) {}).

For more details see jQuery's deferred.progress documentation.

Setup

octokit.js has the following dependencies:

• Underscore
• Base64 (for basic auth or binary files). You can leave this if you are not using basic auth or binary files.

If you are not using NodeJS or requireJS include these before octokit.js:

<script src="lib/underscore-min.js">
<script src="lib/base64.js">

Change Log

0.7.X

Switched to a native request implementation (thanks @mattpass). Adds support for GitHub gists, forks and pull requests.

0.6.X

Adds support for organizations and fixes an encoding issue.

0.5.X

Smart caching of latest commit sha.

0.4.X

Added support for OAuth.

0.3.X

Support for Moving and removing files.

0.2.X

Consider commit messages.

0.1.X

Initial version.