Skip to content

Provide a simple, fast, and clean way to extract repository information from GitHub.

License

Notifications You must be signed in to change notification settings

GitHubToolbox/github-lister-core

Repository files navigation

DevelopersToolbox logo
Github Build Status Release Commits since release

Overview

The gem aims to provide a simple, fast and, clean way to extract organisation and repository information from GitHub. It comes with several methods but it is intentionally limited.

This was written to work as the lookup core for some other projects, but we felt people may be able to make use of it as a standalone library.

External Libraries

We make use of a number of external (3rd party) gems within this project.

Name Source Purpose
Octokit rubygems.org Simple wrapper for the GitHub API
Parallel rubygems.org Run any kind of code in parallel processes

Usage

require 'github-lister-core'

# Not a real token
options = { :token => '1234567890abcdef1234567890abcdef1234567890abcdef' }

GithubListerCore.user_repos(options)

You can access all of the methods using the alias GCL instead of GithubListerCore

Methods

Work out the parameters for each of these!

Function Parameters Purpose
all_repos user_repos + user_org_repos
org_members_repos Details about all repositories in all organisations a user is a member of
org_membership Details about all the organisation a user is a member of (authenticated user or parameter)
org_repos Details about all repositories within an organisation passed via :org or :org_name
user_repos Authenticated username, :user, users, :username or :usernames Details about all of the repositories owned by the user
validate_user User list Validate users list of users, and returns a hash of all usernames and their validity status

Method Returns

All of the exposed methods will return data in JSON format.

Exceptions

Name Meaning
GithubListerCore::InvalidTokenError An invalid GitHub PAT was used
GithubListerCore::MissingTokenError No GitHub PAT was supplied when expected
GithubListerCore::SAMLProtected GitHub PAT not granted access to specific organisation
GithubListerCore::TooManyRequests To many requests made to the GitHub API
GithubListerCore::NotFoundError Requested entity not found (e.g. username or org name)
GithubListerCore::MissingOrganisationError Organisation name not supplied when expected
GithubListerCore::InvalidOptionsHashError The options were not passed as a hash
GithubListerCore::InvalidParameterError The parameter was not supplied as a string or array as expected
GithubListerCore::UnknownError General 'something bad happened' error

Options

Option Name Type Default Value Purpose
:add_languages Boolean false This will add the repository languages to the details (Requires an additional API query per repo)
:add_latest_release Boolean false This will add information about the latest release to the details (Requires an additional API query per repo)
:add_releases Boolean false This will add information about releases to the repository (Requires an additional API query per repo)
:add_topics Boolean false This will add the repository topics to the details (Requires an additional API query per repo)
:add_workflows Boolean false This will add the repository workflow information to the details (Requires an additional API query per repo)
:detailed_orgs Boolean false This will return the full details about an organisation instead of the default abridged version. (Requires an additional API query per organisation)
:org or :org_name String unset The name of the organisation to use when performing queries. (This is only used by the org_repos method and is required for this method)
:org_regex String unset This is the regex pattern you want to use to filter the results for organisations by name
:org_regex_nocase Boolean false Set to true to make organisation name regex matching case insensitive
:regex_nocase Boolean false Set to true to make ALL regex matching case insensitive
:repo_regex String unset This is the regex pattern you want to use to filter the results for repositories by name
:repo_regex_nocase Boolean false Set to true to make repository name regex matching case insensitive
:token String unset The GitHub authentication token (require if no username)
:use_slugs Boolean false This will return only the repo name (:full_name) or the organisation name (:login) instead of the full details
:user, :users, :username or :usernames String unset The GitHub username or names to use when performing queries (If no username is given, the username of the current authenticates user will be used instead)

:user, :users, :username, :usernames, :org, :org_name can be either a single user/organisation name OR a comma-separated list of user/organisation names OR an array of user/organisation names. If more than one name is given, the results for all names will be merged together into one result set.

Contributing

We are always happy for people to contribute, if you want to do so the following information should assist you in setting up a local dev environment.

Please keep in mind the purpose of this tool, it implements a very specific and narrow set of the GitHub API but this is by design, so we may not always accept pull requests if we feel they are taking the project too far beyond its designed scope.

Setup

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Testing

For local testing make sure that you run bundle exec rspec spec and then rake install to install the gem locally.

For further information please refer to the contributing documentation.

Coming soon

There are a number of additional features that we are planning to add in the coming months. All of which will be new options that can be passed to the main methods.

Feature Details
Organisation members Optionally retrieve a list of members within organisations
Outside collaborators Optionally retrieve a list of outside collaborators within organisations
Teams Optionally retrieve a list of teams within organisations
Team members Optionally retrieve a list team members for teams within organisations
Team repositories List repositories for a given team1

1 This can be used the same way as user and organisation listing.

About

Provide a simple, fast, and clean way to extract repository information from GitHub.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published