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.