github

GitHub APIv3 OCaml library
README


This library provides an OCaml interface to the GitHub
APIv3
(JSON). It is compatible with
MirageOS and also compiles to pure JavaScript via
js_of_ocaml.

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.

If you are interested in easily using this library to listen for GitHub
web hook events, you should look at dsheets/ocaml-github-hooks.

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 now use it via the Github_cookie_jar module:

# #require "github.unix";;
# Github_cookie_jar.(init () |> Lwt_main.run |> get ~name:"rwo");;
- : Github_t.auth option =
Some
 {Github_t.auth_scopes = [`Public_repo];
  auth_token = "<token>";
  auth_app =
   {Github_t.app_name = "Real World OCaml";
    app_url = "https://docs.github.com/rest/reference/oauth-authorizations"};
  auth_url = "https://api.github.com/authorizations/236241";
  auth_id = 236241; auth_note = Some "rwo"; 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, repository, status, team add, watch

Not yet supported:

Gists

Supported:

  • All endpoints

Not yet supported:

  • Special media types

  • Truncation helpers

Git Data

Not yet supported: everything (see
#40)

Issues

Supported:

Not yet supported:

Miscellaneous

Supported:

Not yet supported:

Organizations

Supported:

Not yet supported: everything else

Pull Requests

Supported:

  • All endpoints

Not yet supported:

  • Link relations

  • Custom media types

Repositories

Supported:

Not yet supported:

Search

Supported:

Not yet supported:

Users

Supported:

Not yet supported:

Enterprise

Not yet supported: everything

Install
Published
21 Jul 2021
Sources
github-data-4.4.0.tbz
sha256=c36e08b64ba189823d8215c366ff4e9fdbc41c790781246e96cf2c6c1fbb818a
sha512=6588691808a017b11c36031f8e923a47bbc4fd097652b90708cff4626267f0f535a9433dc95cbf1d1b871794a9f9f1391428e5a2f958cc12714c59f351659985
Dependencies
odoc
with-doc
yojson
>= "1.7.0"
github-data
= version
cohttp-lwt
>= "4.0.0"
lwt
>= "2.4.4"
cohttp
>= "4.0.0"
uri
>= "1.9.0"
ocaml
>= "4.08.0"
dune
>= "2.7"
Reverse Dependencies
github-hooks
>= "0.2.0"
github-jsoo
< "3.0.1" | = "4.1.0" | = "4.4.0"
github-unix
= "4.4.0"
opam-publish
>= "2.0.2"