Github API v3 client for Erlang
egithub is implemented as an Erlang application. This means that in order to use it, you
need to add it to your application's .app file or start it with:
application:ensure_all_started(egithub).Once it has started you can start using any of the API calls.
The GitHub's API offers very few endpoints that don't require any credentials and a lot
that do. For providing credentials you have two options: basic authentication or OAuth.
In both cases, you can just call a function from the egithub module to obtain
Credentials, that you can later provide to the functions that require it.
Said functions are:
- [
egithub:basic_auth/2] (http://inaka.github.io/erlang-github/src/egithub.html?i=0&search=egithub:basic#basic_auth/1) - [
egithub:oauth/1] (http://inaka.github.io/erlang-github/src/egithub.html?i=0&search=oauth#oauth/1)
For example to get the information of the logged in user you can do the following:
Cred = egithub:basic_auth("username", "password"),
{ok, UserInfo} = egithub:user(Cred).This library provides the basic functionality over which you can implement your own GitHub
webhook service. The webhook events that are currently supported are only ping and
pull_request. These two allow you to process the contents in a PR, write comments to
it or add a PR review.
To accomplish this you need to implement the egithub_webhook behavior, which requires a
single handle_pull_request/3 callback. This function receives the GitHub's credentials
the PR data and the associated files.
By default, this library uses the GitHub's PR reviews feature. So, once your
handle_pull_request/3 implementation is done processing the PR it will have to return the
tuple {ok, pr_review()}, where pr_review() is a map with information regarding the
Review (e.g. commit_id, body, event, and comments).
In case you want to use individual comments in your PR, you will have to set the review_style
parameter within your application's config file to individual_comments, i.e:
{egithub, [{review_style, individual_comments}]},And then, your handle_pull_request/3 will have to return the tuple {ok, [message()]},
where message() is a map with information regarding the comment (e.g. commit_id, path, etc).
Both, pr_review/0 and message/0 types are documented within the egithub_webhook module.
To start the whole webhook flow once you receive the request from GitHub on your endpoint
you can call either egithub_webhook:event/3 or egithub_webhook:event/6. The function
with arity 3 will just create the comments returned by your implementation. The second
function will also make calls to the Statuses
API and will report on the current
status of the webhook.
If you use the GitHub API to create a lot of entities in a short interval, at a certain point you will hit a limit on the rate of requests you can do. This is sort of documented in the API's documentation, although there are no specifics on the amount of requests permitted or the interval considered.
To work around this limitation, egithub has a built-in detection mechanism that handles
the case where an API call returns 403 after doing a valid requests. The request is
queued and retried after a certain amount of time, based on a fibonacci backoff time
series.
By default all API requests are done without this feature, which means you will get a
403 if you start doing a lot of requests one after the other. If you want to use this
feature you need to provide the value queue for the option post_method. All functions
in the egithub module that accept an Options argument, accept this option.
For example, if you wanted to create a large number of comments on an issue, you could use
the egithub:issue_comment/5 like this:
Cred = egithub:basic_auth("username", "password"),
Repo = "username/reponame",
Issue = 1,
Comment = <<"Hello">>,
Options = #{post_method => queue},
egithub:issue_comment(Cred, Repo, Issue, Comment, Options).This would create a comment with the text Hello for the issue username/repo#1.
There is an automatically generated API documentation page here.
For an example on how to use this library you can check out this little Erlang application used to pull a JSON with all of Inaka's repositories in GitHub.
There is also a lot of code that calls the functions in egithub in the module
egithub_webhook.
If you find any bugs or have a problem while using this library, please open an issue in this repo (or a pull request :)).
And you can check all of our open-source projects at inaka.github.io