Project

ghub

0.0
The project is in a healthy, maintained state
ghubbkuhlmann/ghubHomepageDocumentationSource CodeBug Tracker
A monadic GitHub API client.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
9,749
Stars
5
Forks
0
Watchers
2
 Releases
Current version
0.21.0
Total releases
27
First release
2022-10-20
Latest release
2024-11-09
 Development
Primary Language
Ruby
Licenses
Hippocratic-2.1
Average date of last 50 commits
2024-07-19
Reverse Dependencies
1

 Dependencies

Runtime

infusible
~> 3.12
dry-monads
~> 1.6
dry-schema
~> 1.13
http
~> 5.1
zeitwerk
~> 2.7
refinements
~> 12.10
containable
~> 0.2
pipeable
~> 0.14
 Project Readme

Ghub

Ghub is portmanteau (i.e. [g]it + hub = ghub) that provides a GitHub API client using a design which leverages function composition and monads. This gem is built upon the HTTP gem which provides a nicer Object API instead of Faraday which is what the Octokit gem uses.

Table of Contents
  • Features
  • Requirements
  • Setup
  • Usage
    • Initialization
    • Environment
    • Endpoints
      • Branch Protection
      • Branch Signature
      • Organization Members
      • Pulls
      • Repositories
      • Search
      • Users
  • Development
  • Tests
  • License
  • Security
  • Code of Conduct
  • Contributions
  • Developer Certificate of Origin
  • Versions
  • Community
  • Credits

Features

  • Provides an API client which is a partial implementation of GitHub’s API.

  • Provides HTTP request and response verification using Dry Schema.

  • Uses Function Composition — coupled with Pipeable — to process each HTTP request and response.

Requirements

Setup

To set up the project, run:

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:

client = Ghub::Client.new

Further customization can be done via a block:

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 direnv. These are the defaults:

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 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 show, update, and destroy branch protection:

client.branch_protection.show "<owner>", "<repository>", "<branch>"
client.branch_protection.update "<owner>", "<repository>", "<branch>", {}
client.branch_protection.destroy "<owner>", "<repository>", "<branch>"

Branch Signature

The following is an example of how to show, create, and destroy branch signature protection:

client.branch_signature.show "<owner>", "<repository>", "<branch>"
client.branch_signature.create "<owner>", "<repository>", "<branch>"
client.branch_signature.destroy "<owner>", "<repository>", "<branch>"

Organization Members

The following is how to index organization members.

client.organization_members.index "<owner>"

Pulls

The following is how to index and show pull requests:

client.pulls.index "<owner>", "<repository>"
client.pulls.show "<owner>", "<repository>", <id>

Repositories

The following documents how to interact with repositories:

# Index (user and organization)
# Format: client.repositories.index :<kind>, "<owner>"
client.repositories.index :users, "doe"
client.repositories.index :orgs, "acme"

# Show (user or organization)
# Format: client.repositories.show "<owner>", "<repository>"
client.repositories.show "acme", "ghub-test"

# Create (user and organization)
# Format: client.repositories.create :<kind>, <body>
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 "<owner>", "<repository>", <body>
client.repositories.patch "acme", "ghub-test", {description: "For test only."}

# Destroy (user or organization)
# Format: client.repositories.destroy "<owner>", "<repository>"
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 users:

client.search_users.index q: "test@example.com"

Users

The following is how to index and show users:

client.users.index
client.users.show "<user>"

Development

To contribute, run:

git clone https://github.com/bkuhlmann/ghub
cd ghub
bin/setup

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

bin/console

Tests

To test, run:

bin/rake

Credits