GitHub Integration
Last modified by Vincent Massol on 2024/10/30 16:20
 | Various ways to query the GitHub API using Groovy |
| Type | Snippet |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
Shows how to integrate with GitHub using its REST API, using Groovy to perform the REST calls.
There are 3 main solutions:
- Using Groovy's builtin JSON slurper
- Using the EGit GitHub Java library. This is now old and deprecated
- Using the Kohsuke GitHub API
Note that while using the JSON slurper works well, a lot of GitHub API return paginated results and it's difficult to handle this using the JSON Slurper since it requires getting access to the HTTP response headers.
OTOH using the Java libraries makes this a breeze since it's handled transparently!
Examples with JSON Slurper
List all Git repositories for an organization
Version using the GitHub v3 API:
{{cache}}
{{groovy}}
import groovy.json.*
def url = "https://api.github.com/users/xwiki/repos".toURL().text
def root = new JsonSlurper().parseText(url)
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
root.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
{{groovy}}
import groovy.json.*
def url = "https://api.github.com/users/xwiki/repos".toURL().text
def root = new JsonSlurper().parseText(url)
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
root.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
Version using the GitHub v2 API:
{{cache}}
{{groovy}}
import groovy.json.*
def url = "http://github.com/api/v2/json/repos/show/xwiki".toURL().text
def root = new JsonSlurper().parseText(url)
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
root.repositories.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
{{groovy}}
import groovy.json.*
def url = "http://github.com/api/v2/json/repos/show/xwiki".toURL().text
def root = new JsonSlurper().parseText(url)
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
root.repositories.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
Note: If you wish you could also use Groovy's HttpBuilder (although it's more complex but the example shows how to use the Grape's @Grab annotation):
{{cache}}
{{groovy}}
@Grab(group='org.codehaus.groovy.modules.http-builder', module='http-builder', version='0.5.1')
import groovyx.net.http.RESTClient
github = new RESTClient( 'http://github.com/api/v2/json/' )
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
def response = github.get( path : 'repos/show/xwiki' )
response.data.repositories.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
{{groovy}}
@Grab(group='org.codehaus.groovy.modules.http-builder', module='http-builder', version='0.5.1')
import groovyx.net.http.RESTClient
github = new RESTClient( 'http://github.com/api/v2/json/' )
println "|=Project|=Description|=Use Wiki?|=Use Issues?"
def response = github.get( path : 'repos/show/xwiki' )
response.data.repositories.each() { repo ->
println "|[[${repo.name}>>http://github.com/xwiki/${repo.name}]]|${repo.description}|${repo.has_wiki}|${repo.has_issues}"
}
{{/groovy}}
{{/cache}}
Result:
List all committers for an organization
{{cache}}
{{groovy}}
import groovy.json.*
def committers = [:]
// Find all repositories for the "xwiki" organization
def reposRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/repos/show/xwiki".toURL().text)
reposRoot.repositories.each() { repo ->
// For each repository get the collaborators
def collaboratorsRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/repos/show/xwiki/${repo.name}/collaborators".toURL().text)
collaboratorsRoot.collaborators.each() { collaborator ->
def projects = committers.get(collaborator)
if (projects == null) {
projects = []
committers.put(collaborator, projects)
}
projects.add("[[${repo.name}>>http://github.com/xwiki/${repo.name}]]")
}
}
println("|=Avatar|=Id|=Name|=Company|=Top level modules")
committers.sort().each() { committer, projects ->
// Get information about committer
def userRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/user/show/${committer}".toURL().text)
def user = userRoot.user
println "|[[image:http://www.gravatar.com/avatar/${user. gravatar_id}>>http://github.com/${committer}]]|${committer}|${user.name}|${user.company}|${projects.join(", ")}"
}
{{/groovy}}
{{/cache}}
{{groovy}}
import groovy.json.*
def committers = [:]
// Find all repositories for the "xwiki" organization
def reposRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/repos/show/xwiki".toURL().text)
reposRoot.repositories.each() { repo ->
// For each repository get the collaborators
def collaboratorsRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/repos/show/xwiki/${repo.name}/collaborators".toURL().text)
collaboratorsRoot.collaborators.each() { collaborator ->
def projects = committers.get(collaborator)
if (projects == null) {
projects = []
committers.put(collaborator, projects)
}
projects.add("[[${repo.name}>>http://github.com/xwiki/${repo.name}]]")
}
}
println("|=Avatar|=Id|=Name|=Company|=Top level modules")
committers.sort().each() { committer, projects ->
// Get information about committer
def userRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/user/show/${committer}".toURL().text)
def user = userRoot.user
println "|[[image:http://www.gravatar.com/avatar/${user. gravatar_id}>>http://github.com/${committer}]]|${committer}|${user.name}|${user.company}|${projects.join(", ")}"
}
{{/groovy}}
{{/cache}}
Result:
List last commits on a project/branch
For example to list latest commits for the XWiki organization on the master branch of the xwiki-commons project. Note that we also add a link when recognizing a JIRA URL 
{{groovy}}
import groovy.json.*
println("|=Author|=Date|=Commit Message|=Details")
def commitsRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/commits/list/xwiki/xwiki-commons/master".toURL().text)
commitsRoot.commits.each() { commit ->
def message = (commit.message =~ /([A-Z]+-\d+)/).replaceAll('[[$1>>http://jira.xwiki.org/browse/$1]]')
println "|${commit.author.name} (${commit.author.login})|${commit.committed_date}|((("
println message
println ")))|[[View>>http://github.com${commit.url}]]"
}
{{/groovy}}
import groovy.json.*
println("|=Author|=Date|=Commit Message|=Details")
def commitsRoot = new JsonSlurper().parseText("http://github.com/api/v2/json/commits/list/xwiki/xwiki-commons/master".toURL().text)
commitsRoot.commits.each() { commit ->
def message = (commit.message =~ /([A-Z]+-\d+)/).replaceAll('[[$1>>http://jira.xwiki.org/browse/$1]]')
println "|${commit.author.name} (${commit.author.login})|${commit.committed_date}|((("
println message
println ")))|[[View>>http://github.com${commit.url}]]"
}
{{/groovy}}
Result:
Examples with Kohsuke GitHub API
First, you need to install the java library in XWiki, using the Extension Manager:
- Extension id: org.kohsuke:github-api
- Version: 1.326 (to be adapted, this the latest at the date of writing)
If you wish to connect using a Personal Access Token (PAT), replace the call to GitHub.connectAnonymously() with GitHub.connectUsingOAuth("your PAT here").
List all repositories and their creation dates
{{groovy}}
import org.kohsuke.github.*
def github = GitHub.connectAnonymously()
def organization = github.getOrganization('xwiki-contrib')
def repos = organization.listRepositories()
println "|=Repository name|=Created At"
repos.each() {
println "|${it.name}|${it.createdAt}"
}
{{/groovy}}
import org.kohsuke.github.*
def github = GitHub.connectAnonymously()
def organization = github.getOrganization('xwiki-contrib')
def repos = organization.listRepositories()
println "|=Repository name|=Created At"
repos.each() {
println "|${it.name}|${it.createdAt}"
}
{{/groovy}}
Variation: List of all repos created between 2 dates (2023-06-30 - 2024-06-30 in this example):
{{groovy}}
import org.kohsuke.github.*
def github = GitHub.connectAnonymously()
def organization = github.getOrganization('xwiki-contrib')
def after = new GregorianCalendar(2023, Calendar.JUNE, 30).time
def before = new GregorianCalendar(2024, Calendar.JUNE, 30).time
def total = 0
println "|=Repository name|=Created At"
def repos = organization.listRepositories()
repos.each() {
def creationDate = it.createdAt
if (creationDate.after(after) && creationDate.before(before)) {
println "|${it.name}|${it.createdAt}"
total++
}
}
println ""
println "total matching repos: ${total}"
{{/groovy}}
import org.kohsuke.github.*
def github = GitHub.connectAnonymously()
def organization = github.getOrganization('xwiki-contrib')
def after = new GregorianCalendar(2023, Calendar.JUNE, 30).time
def before = new GregorianCalendar(2024, Calendar.JUNE, 30).time
def total = 0
println "|=Repository name|=Created At"
def repos = organization.listRepositories()
repos.each() {
def creationDate = it.createdAt
if (creationDate.after(after) && creationDate.before(before)) {
println "|${it.name}|${it.createdAt}"
total++
}
}
println ""
println "total matching repos: ${total}"
{{/groovy}}
Examples with EGit GitHub Java API
List all repositories and their creation dates
{{groovy}}
@Grab(group='org.eclipse.mylyn.github', module='org.eclipse.egit.github.core', version='2.1.5')
import org.eclipse.egit.github.core.service.*
RepositoryService service = new RepositoryService()
def repos = service.getRepositories("xwiki-contrib")
println "total repos: ${repos.size()}"
println ""
println "|=Repository name|=Created At"
repos.each() {
println "|${it.name}|${it.createdAt}"
}
{{/groovy}}
@Grab(group='org.eclipse.mylyn.github', module='org.eclipse.egit.github.core', version='2.1.5')
import org.eclipse.egit.github.core.service.*
RepositoryService service = new RepositoryService()
def repos = service.getRepositories("xwiki-contrib")
println "total repos: ${repos.size()}"
println ""
println "|=Repository name|=Created At"
repos.each() {
println "|${it.name}|${it.createdAt}"
}
{{/groovy}}
Variation: List of all repos created between 2 dates (2013-06-30 - 2014-06-30 in this example):
{{groovy}}
@Grab(group='org.eclipse.mylyn.github', module='org.eclipse.egit.github.core', version='2.1.5')
import org.eclipse.egit.github.core.service.*
RepositoryService service = new RepositoryService()
println "|=Repository name|=Created At"
def after = new GregorianCalendar(2013, Calendar.JUNE, 30).time
def before = new GregorianCalendar(2014, Calendar.JUNE, 30).time
def total = 0
service.getRepositories("xwiki-contrib").each() {
def creationDate = it.createdAt
if (creationDate.after(after) && creationDate.before(before)) {
println "|${it.name}|${it.createdAt}"
total++
}
}
println ""
println "total matching repos: ${total}"
{{/groovy}}
@Grab(group='org.eclipse.mylyn.github', module='org.eclipse.egit.github.core', version='2.1.5')
import org.eclipse.egit.github.core.service.*
RepositoryService service = new RepositoryService()
println "|=Repository name|=Created At"
def after = new GregorianCalendar(2013, Calendar.JUNE, 30).time
def before = new GregorianCalendar(2014, Calendar.JUNE, 30).time
def total = 0
service.getRepositories("xwiki-contrib").each() {
def creationDate = it.createdAt
if (creationDate.after(after) && creationDate.before(before)) {
println "|${it.name}|${it.createdAt}"
total++
}
}
println ""
println "total matching repos: ${total}"
{{/groovy}}
Prerequisites & Installation Instructions
- If you're using an XWiki version lower than 3.2:
- Download the Ivy JAR and copy it in your WEB-INF/lib directory. This is needed by the Groovy @Grab directive.
- If you're using XWiki 3.2+ then you're good to go!
