GitHub APIv3 OCaml Library

This library provides an OCaml interface to the GitHub APIv3 (JSON).

It is not yet complete but lib/github.atd contains the data types that have been bound so far.

There are several tests and examples in lib_test for small bits of functionality. jar contains utility programs that use the git jar facility for stored tokens.

Debugging

Two environment variables will cause more debugging to be output:

GITHUB_DEBUG=1   # API calls output to stderr
COHTTP_DEBUG=1   # even more HTTP-level debugging

If using the bindings from the toplevel, you can also set Github.log_active to true to get the same effect as setting the GITHUB_DEBUG environment variable.

git jar

Applications that use this library will need to save authorization tokens locally, and the Github_cookie_jar module in unix helps handle this more naturally. It maps local application name to an authorization token so that the application can query the cookie jar at runtime and use the resulting token in Github API calls.

The tokens are all stored in $HOME/.github/jar/<name>, where <name> is the local name of the application.

A git-jar command will be installed to add, remove, and list the contents of this cookie jar.

$ git jar

...will display the man page.

$ git jar make avsm rwo
Enter Github password: **********
Enter 2FA code from 'app': 172217
Github cookie jar: created /home/avsm/.github/jar/rwo
Created token rwo (236241): <token>

$ git jar show avsm
Enter Github password: **********
Enter 2FA code from 'app': 001221
Cookie Name | ID       | Application                              | Note      
----------------------------------------------------------------------------------
        rwo | 236241   | Real World OCaml (API)                   |
   <remote> | 340988   | Travis                                   |

Your Github application can how use it via the Github_cookie_jar module:

# #require "github.unix";;
# Github_cookie_jar.get ~name:"rwo";;
- : Github_t.auth option = Some 
  { Github_t.auth_scopes = [`Public_repo];
    Github_t.auth_token = "<token>";
    Github_t.auth_app = {
      Github_t.app_name = "Real World OCaml";
      Github_t.app_url = "http://realworldocaml.org/" };
    Github_t.auth_url = "https://api.github.com/authorizations/236241";
    Github_t.auth_id = 236241; Github_t.auth_note = None; 
    Github_t.auth_note_url = None }

Manipulate GitHub releases

The Releases API in GitHub cannot itself be synched via Git, so this command-line tool lets you specify a source user/repo and destination user/repo pair, and copies all the releases from one to the other.

The git-sync-releases binary can copy all the releases from one repository to another for you.

$ git sync-releases mirage ocaml-uri avsm ocaml-uri

You can also associate binary files with any release, for example to include pregenerated build files. The git upload-release binary will do this for you.

$ git upload-release mirage ocaml-uri v1.4.0 release.tar.gz

API support coverage

Media Types

Supported: application/vnd.github.v3+json

Not yet supported: Other media types

OAuth

Supported:

• Web and non-Web flows with two-factor authentication
• Basic Authorizations API

Not yet supported:

• Check (see #83)
• Reset (see #83)
• Fingerprint retrieval (see #83)
• get-or-create, update, revoke
• fingerprint endpoints

Activity

Supported:

• All Events endpoints
• Event types: commit comment, create, delete, deployment, deployment status, download, follow, fork, fork apply, gist, gollum, issue comment, issues, member, page build, public, pull request, pull request review comment, push, release, status, team add, watch

Not yet supported:

• Event types: membership, repository
• Feeds
• Notifications
• Starring
• Watching

Gists

Supported:

• All endpoints

Not yet supported:

• Special media types
• Truncation helpers

Git Data

Not yet supported: everything (see #40)

Issues

Supported:

• All basic endpoints
• Basic comments endpoints
• Milestones

Not yet supported:

• Custom media types
• Assignees
• Repository issue comments
• Get a single issue comment
• Edit an issue comment (see #87)
• Delete an issue comment
• Issue events
• Several issue event type
• Labels

Miscellaneous

Supported:

• Rate limit

Not yet supported:

• Emojis
• Gitignore
• Markdown
• Meta
• Licenses

Organizations

Supported:

• List teams
• Get team
• List team repos

Not yet supported: everything else

Pull Requests

Supported:

• All endpoints

Not yet supported:

• Link relations
• Custom media types

Repositories

Supported:

• List user repositories
• Get
• List tags
• List branches
• Get a single commit
• Deploy keys
• Forks
• Most Releases endpoints
• Create a status
• List statuses for a specific ref
• Most Webhooks endpoints

Not yet supported:

• List your repositories
• List organization repositories
• List all public repositories
• Create
• Edit
• List contributors
• List languages
• List teams
• Get branch
• Delete repository
• Collaborators
• Commit comments
• List commits
• Compare two commits
• Contents
• Deployments
• Merging
• Pages
• Get the latest release
• Get a release by tag name
• List assets for a release
• Get a single release asset
• Edit a release asset
• Delete a release asset
• Statistics (see #86)
• Get the combined status for a specific ref
• Ping a hook
• PubSubHubbub
• Receiving Webhooks helpers

Search

Supported:

• Search repositories

Not yet supported:

• Search code
• Search issues
• Search users
• Text match media type

Users

Supported:

• Get a single user
• Get the authenticated user

Not yet supported:

• Update the authenticated user
• Get all users

Enterprise

Not yet supported: everything