Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/ghub

A monadic GitHub API client.
https://github.com/bkuhlmann/ghub

api client git github

Last synced: 2 days ago
JSON representation

A monadic GitHub API client.

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



:pipeable_link: link:https://alchemists.io/projects/pipeable[Pipeable]



= Ghub



Ghub is portmanteau (i.e. [g]it + hub = ghub) that provides a GitHub link:https://docs.github.com/en/rest[API] client using a design which leverages link:https://alchemists.io/articles/ruby_function_composition[function composition] and link:https://dry-rb.org/gems/dry-monads[monads]. This gem is built upon the link:https://github.com/httprb/http[HTTP] gem which provides a nicer Object API instead of link:https://lostisland.github.io/faraday[Faraday] which is what the link:https://github.com/octokit/octokit.rb[Octokit] gem uses.



toc::[]



== Features



* Provides an API client which is a partial implementation of GitHub's link:https://docs.github.com/en/rest[API].

* Provides HTTP request and response verification using link:https://dry-rb.org/gems/dry-schema[Dry Schema].

* Uses link:https://alchemists.io/articles/ruby_function_composition[Function Composition] -- coupled with {pipeable_link} -- to process each HTTP request and response.



== Requirements



. link:https://www.ruby-lang.org[Ruby].

. link:https://github.com[GitHub].



== Setup



To set up the project, run:



[source,bash]

----

bin/setup

----



== Usage



All usage is via the `Ghub::Client` class.



=== Initialization



You can initialize an API client -- using the defaults as described in the _Environment_ section below -- as follows:



[source,ruby]

----

client = Ghub::Client.new

----



Further customization can be done via a block:



[source,ruby]

----

client = Ghub::Client.new do |config|

  config.accept = "application/json"     # Uses a custom HTTP Accept header.

  config.paginate = true                 # Enabled automatic pagination.

  config.token = "ghp_abc"               # Provides a Personal Access Token (PAT).

  config.url = "https://alt.github.com"  # Uses a custom API root.

end

----



=== Environment



Environment variable support can be managed using link:https://direnv.net[direnv]. These are the defaults:



[source,bash]

----

GITHUB_API_ACCEPT=application/vnd.github+json

GITHUB_API_PAGINATE=false

GITHUB_API_TOKEN=

GITHUB_API_URL=https://api.github.com

----



_You must provide a value for `GITHUB_API_TOKEN` in order to make authenticated API requests._ This can be done by creating a link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[Personal Access Token (PAT)] for the value.



=== Endpoints



Only partial support of the various API endpoints are supported. Each section below documents usage with additional documentation, usage, parameters, responses, etc. provided by the official GitHub API documentation links.



==== Branch Protection



The following is an example of how to link:https://docs.github.com/en/rest/branches/branch-protection#get-branch-protection[show], link:https://docs.github.com/en/rest/branches/branch-protection#update-branch-protection[update], and link:https://docs.github.com/en/rest/branches/branch-protection#delete-branch-protection[destroy] branch protection:



[source,ruby]

----

client.branch_protection.show "", "", ""

client.branch_protection.update "", "", "", {}

client.branch_protection.destroy "", "", ""

----



==== Branch Signature



The following is an example of how to link:https://docs.github.com/en/rest/branches/branch-protection#get-commit-signature-protection[show], link:https://docs.github.com/en/rest/branches/branch-protection#create-commit-signature-protection[create], and link:https://docs.github.com/en/rest/branches/branch-protection#delete-commit-signature-protection[destroy] branch signature protection:



[source,ruby]

----

client.branch_signature.show "", "", ""

client.branch_signature.create "", "", ""

client.branch_signature.destroy "", "", ""

----



==== Organization Members



The following is how to link:https://docs.github.com/en/rest/orgs/members#list-organization-members[index] organization members.



[source,ruby]

----

client.organization_members.index ""

----



==== Pulls



The following is how to link:https://docs.github.com/en/rest/pulls/pulls#list-pull-requests[index] and link:https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request[show] pull requests:



[source,ruby]

----

client.pulls.index "", ""

client.pulls.show "", "", 

----



==== Repositories



The following documents how to interact with repositories:



* link:https://docs.github.com/en/rest/repos/repos#list-repositories-for-a-user[Index] (users)

* link:https://docs.github.com/en/rest/repos/repos#list-organization-repositories[Index] (organizations)

* link:https://docs.github.com/en/rest/repos/repos#get-a-repository[Show]

* link:https://docs.github.com/en/rest/repos/repos#create-a-repository-for-the-authenticated-user[Create] (user)

* link:https://docs.github.com/en/rest/repos/repos#create-an-organization-repository[Create] (organization)

* link:https://docs.github.com/en/rest/repos/repos#update-a-repository[Update]

* link:https://docs.github.com/en/rest/repos/repos#delete-a-repository[Destroy]



[source,ruby]

----

# Index (user and organization)

# Format: client.repositories.index :, ""

client.repositories.index :users, "doe"

client.repositories.index :orgs, "acme"



# Show (user or organization)

# Format: client.repositories.show "", ""

client.repositories.show "acme", "ghub-test"



# Create (user and organization)

# Format: client.repositories.create :, 

client.repositories.create :users, {name: "ghub-test", private: true}

client.repositories.create :orgs, {name: "ghub-test", private: true}, owner: "acme"



# Patch (user or organization)

# Format: client.repositories.patch "", "", 

client.repositories.patch "acme", "ghub-test", {description: "For test only."}



# Destroy (user or organization)

# Format: client.repositories.destroy "", ""

client.repositories.destroy "acme", "ghub-test"

----



GitHub's API design for repositories is awkward and you can see this infect the Object API, especially when creating a repository. Use `:users` or `:orgs` (can be strings) to distinguish between the two types of repository creation. The only stipulation for organization creation is that you must supply the organization name. This was done so you could use the same Object API for both.



==== Search



The following is how to search link:https://docs.github.com/en/rest/search/search#search-users[users]:



[source,ruby]

----

client.search_users.index q: "[email protected]"

----



==== Users



The following is how to link:https://docs.github.com/en/rest/users/users#list-users[index] and link:https://docs.github.com/en/rest/users/users#get-a-user[show] users:



[source,ruby]

----

client.users.index

client.users.show ""

----



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/ghub

cd ghub

bin/setup

----



You can also use the IRB console for direct access to all objects:



[source,bash]

----

bin/console

----



== Tests



To test, run:



[source,bash]

----

bin/rake

----



== link:https://alchemists.io/policies/license[License]



== link:https://alchemists.io/policies/security[Security]



== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]



== link:https://alchemists.io/policies/contributions[Contributions]



== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]



== link:https://alchemists.io/projects/ghub/versions[Versions]



== link:https://alchemists.io/community[Community]



== Credits



* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].