GitHub (Jervis 2.2 API)

net.gleske.jervis.remotes.GitHub

All Implemented Interfaces and Traits:: JervisRemote, SimpleRestServiceSupport

class GitHub
extends Object

A simple class to interact with the GitHub v3 API for only the parts I need.

Sample usage

To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.

Basic usage


import net.gleske.jervis.remotes.GitHub

GitHub github = new GitHub()
println 'Print each branch.'
github.branches('samrocketman/jervis').each{ println it }
println 'Print the contents of .travis.yml from the main branch.'
println github.getFile('samrocketman/jervis','.travis.yml','main')

Using a GitHub App to upload security code analysis

GitHub supports SARIF format for uploading code analysis results. This is a code example of uploading the report to a reference. The GitHub App requires read and write for Code scanning alerts. This example illustrates a more advanced example of utilizing this library with GitHub REST APIs.


import net.gleske.jervis.remotes.GitHub
import net.gleske.jervis.remotes.creds.EphemeralTokenCache
import net.gleske.jervis.remotes.creds.GitHubAppCredential
import net.gleske.jervis.remotes.creds.GitHubAppRsaCredentialImpl
import net.gleske.jervis.tools.GZip
import net.gleske.jervis.tools.SecurityIO

GitHubAppRsaCredentialImpl rsaCred = new GitHubAppRsaCredentialImpl('123456', new File('app-private-key.pem').text)
rsaCred.owner = 'gh-organization'
EphemeralTokenCache tokenCache = new EphemeralTokenCache('src/test/resources/rsa_keys/good_id_rsa_4096')

GitHubAppCredential apiCredential = new GitHubAppCredential(rsaCred, tokenCache)
// uncomment this if rsaCred.owner is a user (as opposed to organization)
// apiCredential.ownerIsUser = true

// instantiate API client with GitHub App credential
GitHub github = new GitHub()
github.credential = apiCredential

// create sarif data; for example
// gitleaks detect -f sarif -r sarif.json

ByteArrayOutputStream compressed = new ByteArrayOutputStream()
// best speed (1) compression
new GZip(compressed, 1).withCloseable {
    it << new FileInputStream('sarif.json')
}

Map data = [
    commit_sha: '6de5066d241a0a30576c8685874b90aa12441a87',
    ref: 'refs/heads/main',
    sarif: SecurityIO.encodeBase64(compressed.toByteArray())
]

// make API call to GitHub code-scanning
github.apiFetch('repos/samrocketman/jervis/code-scanning/sarifs', [:], 'POST', data)

Properties Summary

Properties
Type	Name and description
`TokenCredential`	`credential` A credential for interacting with an external credential store.
`String`	`gh_api` URL to the GitHub v3 API.
`String`	`gh_clone` The base clone URI in which repositories will be cloned.
`String`	`gh_token` The API token, which can be used to communicate with GitHub using authentication.
`String`	`gh_web` URL to the GitHub web interface.
`Map`	`headers` Optional HTTP headers that can be added to every request.

Methods Summary

Methods
Type Params	Return Type	Name and description
	`String`	`baseUrl()`
	`List`	`branches(String project)` Get a list of branches for a project.
	`def`	`fetch(String path)` Fetches a `URL` from GitHub API.
	`String`	`getCloneUrl()` Get the contents of `gh_clone`.
	`String`	`getFile(String project, String file_path, String ref = '')` Get the contents of a file from a project.
	`ArrayList`	`getFolderListing(String project, String dir_path = '/', String ref = '')` Get the directory listing of a path from a project.
	`String`	`getGh_token()` Retrieves the token used to authenticate with GitHub.
	`String`	`getWebUrl()` Get the contents of `gh_web`.
	`Map`	`header(Map headers = [:])`
	`boolean`	`isUser(String user)` Check with the GitHub API and determine if the passed in `user` is a User or an Organization.
	`void`	`setCredential(TokenCredential c)`
	`void`	`setGh_api(String gh_api)` Sets the `gh_api` property.
	`void`	`setGh_clone(String gh_clone)` Sets the `gh_clone` property.
	`void`	`setGh_token(String token)` Sets the token to be used by GitHub.
	`void`	`setGh_web(String gh_web)` Sets the `gh_web` and `gh_api` properties.
	`String`	`toString()` Get a human readable string for this type of remote.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`equals, toString, hashCode, getClass, notify, notifyAll, wait, wait, wait`

- Property Detail
  - TokenCredential credential
    
    A credential for interacting with an external credential store. If this is defined or set, then gh_token is ignored and not used. Default: null
  - String gh_api
    
    URL to the GitHub v3 API. For GitHub Enterprise it should be gh_web + 'api/v3/'. Default: https://api.github.com/
  - String gh_clone
    
    The base clone URI in which repositories will be cloned. Default: https://github.com/
  - String gh_token
    
    The API token, which can be used to communicate with GitHub using authentication. Default: null
  - String gh_web
    
    URL to the GitHub web interface. Default: https://github.com/
  - Map headers
    
    Optional HTTP headers that can be added to every request.
- Method Detail
  - @Override String baseUrl()
  - List branches(String project)
    
    Get a list of branches for a project. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    Parameters:
    project - A GitHub project including the org. e.g. "samrocketman/jervis"
    Returns:
    A List where each element is a branch in the project.
  - def fetch(String path)
    
    Fetches a URL from GitHub API. This is mostly used by other functions to provide minimum functionality defined in JervisRemote. It can be used for general GitHub API communication.
    Parameters:
    path - A GitHub API path to fetch. The URL must return JSON content. e.g. user/repos.
    Returns:
    A Map or List from the parsed JSON response.
  - String getCloneUrl()
    
    Get the contents of gh_clone. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    Returns:
    The contents of gh_clone.
  - String getFile(String project, String file_path, String ref = '')
    
    Get the contents of a file from a project. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    returns:
    A String which contains the contents of the file requested.
    
    Parameters:
    project - A GitHub project including the org. e.g. "samrocketman/jervis"
    file_path - A path to a file relative to the root of the Git repository. e.g. ".travis.yml"
    ref - A git reference such as a branch, tag, or SHA1 hash. e.g. "main". This option is optional. If not specified the default branch is selected.
  - ArrayList getFolderListing(String project, String dir_path = '/', String ref = '')
    
    Get the directory listing of a path from a project. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    returns:
    An ArrayList which contains the contents of the file requested.
    
    Parameters:
    project - A GitHub project including the org. e.g. samrocketman/jervis
    dir_path - A path to a directory relative to the root of the Git repository. This is optional. By default is / (the repository root).
    ref - A git reference such as a branch, tag, or SHA1 hash. e.g. main. This option is optional.
  - String getGh_token()
    
    Retrieves the token used to authenticate with GitHub. If credential is set, then this will get the credential token, instead of gh_token.
    Returns:
    A personal access token or an OAuth access token typically.
  - String getWebUrl()
    
    Get the contents of gh_web. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    Returns:
    The contents of gh_web.
  - @Override Map header(Map headers = [:])
  - boolean isUser(String user)
    
    Check with the GitHub API and determine if the passed in user is a User or an Organization.
    returns:
    true if it is a user or false if it is not a user.
    
    Parameters:
    user - A user name or organization name to test if it is a user.
  - void setCredential(TokenCredential c)
  - void setGh_api(String gh_api)
    
    Sets the gh_api property.
  - void setGh_clone(String gh_clone)
    
    Sets the gh_clone property.
  - void setGh_token(String token)
    
    Sets the token to be used by GitHub. If credential is set, then this will set the credential token, instead of gh_token.
    Parameters:
    token - A personal access token or an OAuth access token typically.
  - void setGh_web(String gh_web)
    
    Sets the gh_web and gh_api properties. This automatically sets gh_api based on gh_web.
  - String toString()
    
    Get a human readable string for this type of remote. This is meant to be a standard function for Jervis to interact with remotes. All remotes are required to have this function.
    Returns:
    A human readable String for this type of remote. Value returned will be either "GitHub" or "GitHub Enterprise" depending on whether or not gh_web has been set.

Summary:
Property
Method

| Detail:
Property
Method

Jervis API documentation.

[Groovy] Class GitHub

Sample usage

Basic usage

Using a GitHub App to upload security code analysis

Properties Summary

Methods Summary

Inherited Methods Summary

Property Detail

TokenCredential credential

String gh_api

String gh_clone

String gh_token

String gh_web

Map headers

Method Detail

@Override String baseUrl()

List branches(String project)

def fetch(String path)

String getCloneUrl()

String getFile(String project, String file_path, String ref = '')

ArrayList getFolderListing(String project, String dir_path = '/', String ref = '')

String getGh_token()

String getWebUrl()

@Override Map header(Map headers = [:])

boolean isUser(String user)

void setCredential(TokenCredential c)

void setGh_api(String gh_api)

void setGh_clone(String gh_clone)

void setGh_token(String token)

void setGh_web(String gh_web)

String toString()