eXist-db library module to interact with GitHub via the GitHub API v3
The GitHub API XQuery Library provides XQuery functions for interacting with the GitHub API (version 3.0).
This library currently supports the following interactions with GitHub:
This code was written by Winona Salesky as part of the Srophé App, a digital humanities application
developed by Syriaca.org: The Syriac Reference Portal [http://syriaca.org/] and LOGAR: Linked Open Gazetteer of the
Andean Region [http://logarandes.org/] at Vanderbilt University. Funding was provided by The National Endowment for the Humanities,
La Fondazione Internazionale Premio Balzan, the Trans-Institutional Digital Cultural Heritage Cluster at Vanderbilt University,
and the Center of Digital Humanities Research at Texas A&M University.
The package can be installed via the eXist-db package manager.
Import module:import module namespace githubxq="http://exist-db.org/lib/githubxq";
Create a new branch on GitHub
githubxq:branch($base as xs:string?,
$branch as xs:string,
$repo as xs:string,
$authorization-token as xs:string)
Parameters:
Example:
githubxq:branch('master',
'newBranchName',
'https://api.github.com/repos/wsalesky/blogs',
'AUTHORIZATION-TOKEN')
Send a commit to GitHub. *A single file.
githubxq:commit($data as item()*,
$path as xs:string*,
$serialization as xs:string?,
$encoding as xs:string?,
$branch as xs:string?,
$commit-message as xs:string?,
$repo as xs:string,
$authorization-token as xs:string)
Parameters:
Example:
let $data1 := doc('/db/apps/ba-data/data/bibl/tei/2G3TK7GI.xml')
return
githubxq:commit($data1,
'/db/apps/ba-data/data/bibl/tei/2G3TK7GI.xml',
'xml',
'utf-8',
'newBranchName',
'Add new file to newBranchName',
'https://api.github.com/repos/wsalesky/blogs',
'AUTHORIZATION-TOKEN')
Create a new pull request.
githubxq:pull-request($title as xs:string?,
$body as xs:string?,
$branch as xs:string?,
$base as xs:string,
$repo as xs:string,
$authorization-token as xs:string)
Parameters:
Example:
githubxq:pull-request('Merge newBranchName',
'Merge changes made to newBranchName into the master branch',
'master',
'newBranchName',
'https://api.github.com/repos/wsalesky/blogs',
'AUTHORIZATION-TOKEN')
Respond to GitHub webhook requests. Use this function to create an endpoint to respond to GitHub webhook requests.
The script evaluates the request and takes appropriate action based on the contents of the request; uploads new files, updates existing files or deleting files.
This can be a useful method of keeping your eXist-db up to date with edits happening on GitHub, a common workflow for distributed teams
of developers. If the $branch
parameter is used the webhook will respond to requests from the named branch, otherwise the webhook
responds to activity in the master branch.
githubxq:execute-webhook($data as item()*,
$application-path as xs:string,
$repo as xs:string,
$branch as xs:string?,
$key as xs:string,
$rateLimitToken as xs:string?)
Parameters:
Example:
let $data := request:get-data()
return
githubxq:execute-webhook($data,
'/db/apps/ba-data',
'https://github.com/wsalesky/blogs/',
'OPTIONAL-BRANCH',
'YOUR-SECRET-KEYE',
'OPTIONAL-RATE-LIMIT-KEY')
Note: The XQuery responding to GitHub must be run with elevated privileges in order to save and edit the files in your application.
Example: sm:chmod(xs:anyURI('YOUR-ENDPOINT.xql'), "rwsr-xr-x")
Read about webhooks here: [https://developer.github.com/webhooks/]
Webhook settings: