class GitHubGraphQL extends Object
A simple class to interact with the GitHub v4 GraphQL API.
To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.
For more GraphQL samples see Jervis issue number 133.
import net.gleske.jervis.remotes.GitHubGraphQL
GitHubGraphQL github = new GitHubGraphQL()
github.token = 'GitHub personal access token here with no scopes necessary'
String graphql = '''
query {
repository(owner: "samrocketman", name: "jervis") {
jervisYaml:object(expression: "master:.jervis.yml") {
...file
}
travisYaml:object(expression: "master:.travis.yml") {
...file
}
rootFolder:object(expression: "master:") {
...file
}
}
}
fragment file on GitObject {
... on Blob {
text
}
... on Tree {
file:entries {
name
}
}
}
'''
// Make an API call to GitHub
Map response = github.sendGQL(graphql)
// Process the data returned from GitHub
if(['.jervis.yml', '.travis.yml'].intersect((response.data.repository.rootFolder?.file*.name) ?: [])) {
println response.data.repository.with {
it.jervisYaml?.text ?: it.travisYaml?.text
}
}
| Type | Name and description |
|---|---|
TokenCredential |
credentialA credential for interacting with an external credential store. |
String |
gh_apiURL to the GitHub v4 GraphQL API. |
String |
tokenThe API token, which can be used to communicate with GitHub using authentication. |
| Type Params | Return Type | Name and description |
|---|---|---|
|
String |
baseUrl()A method which returns the base URL for the GitHub v4 GraphQL API. |
|
String |
getGqlData(String query, String variables = '')Transforms a GraphQL query and variables into data which can be submitted with a POST request. |
|
Map |
getJervisYamlFiles(String owner, String repository, List gitRefs = ['refs/heads/master'], List yamlFiles = ['.jervis.yml')Get Jervis YAML from a remote repository. |
|
Map |
getJervisYamlFiles(String repositoryWithOwner, List gitRefs = ['refs/heads/master'], List yamlFiles = ['.jervis.yml')Get Jervis YAML from a remote repository. |
|
String |
getToken()Retrieves the token used to authenticate with GitHub. |
|
Map |
header(Map http_headers = [:])A method which sets authentication headers. |
|
def |
sendGQL(String graphql, String variables = '', String http_method = 'POST', Map http_headers = [:])A method for calling the GitHub v4 GraphQL API with a GraphQL query and variables. |
|
void |
setToken(String token)Sets the token to be used by GitHub. |
A credential for interacting with an external credential store. If this is defined or set, then token is ignored and not used. Default: null
URL to the GitHub v4 GraphQL API. Default: https://api.github.com/graphql
A method which returns the base URL for the GitHub v4 GraphQL API. This method is not meant to be called by end users.
Transforms a GraphQL query and variables into data which can be submitted with a POST request. This is used by sendGQL to submit transformed GraphQL to the GitHub API v4 GraphQL.
query - A GraphQL query.variables - GraphQL variables meant to be used by a GraphQL query.Get Jervis YAML from a remote repository. It supports getting YAML from multiple branches at once (gitRefs and from multiple alternate YAML file locations (yamlFiles).
owner - GitHub repository owner such as an Organization or User.
e.g. GitHub user
samrocketman.repository - The name of the repository. e.g.
jervis.gitRefs - A list of get references (branches, tags, commits, etc)
in order to retrieve files. By default, the value
['refs/heads/master'].yamlFiles - A list of YAML files to try getting the Jervis YAML
contents from. By default, the value is
['.jervis.yml', '.travis.yml'].Call with default arguments
import net.gleske.jervis.remotes.GitHubGraphQL
GitHubGraphQL github = new GitHubGraphQL()
github.token = new File('../github_token').text.trim()
// Make an API call to GitHub
Map response = github.getJervisYamlFiles('samrocketman', 'jervis')
Responds with parsed data
[
gitRef0: [
jervisYaml0: null,
jervisYaml1: [
text: 'language: groovy\\n'
]
rootFolder: [
file: [
[
name: ".travis.yml",
type: "blob"
],
[
name: "src",
type: "tree"
]
]
]
]
]
The above response indicates there was no .jervis.yml, but there was a .travis.yml file.
Files returned are typically one of three types:
Get Jervis YAML from a remote repository. It supports getting YAML from multiple branches at once (gitRefs and from multiple alternate YAML file locations (yamlFiles).
repositoryWithOwner
- A repository URL which includes the GitHub owner. e.g.
samrocketman/jervis.gitRefs - A list of get references (branches, tags, commits, etc)
in order to retrieve files. By default, the value
['refs/heads/master'].yamlFiles - A list of YAML files to try getting the Jervis YAML
contents from. By default, the value is
['.jervis.yml', '.travis.yml'].Retrieves the token used to authenticate with GitHub. If credential is set, then this will get the credential token, instead of token.
A method which sets authentication headers. This method is not meant to be called by end users.
A method for calling the GitHub v4 GraphQL API with a GraphQL query and variables.
graphql - A GraphQL query.variables - GraphQL variables meant to be used by a GraphQL query.http_method - Customize the method to be submitted to the GitHub
GraphQL API. Typically POST, but could be
another method if performing a mutation.http_headers - Add custom HTTP headers. This does not normally need
to be called but is available for customization.Sets the token to be used by GitHub. If credential is set then this will set the credential token, instead of token.
token - A personal access token or an OAuth access token typically.