-
Notifications
You must be signed in to change notification settings - Fork 11
GitHub
Load the package
<<BTools`External`
The main function here is GitHub
, which is a general purpose wrapper encapsulating everything to do with the github API .
A request is generally formatted like so:
GitHub["Name", params...]
You can also specify a return format. These can be any of
-
"HTTPRequest"
— theHTTPRequest
to be passed -
"HTTPResponse"
— theHTTPResponse
returned -
"ResultJSON"
— the result imported as"JSON"
-
"ImportedResult"
— the JSON result imported as formattedAssociation
. This is default return format. -
"ResultObject"
— the result imported as"ResultObject"
(Success
orFailure
)
There are also two special parameters that may be requested in place of the params
:
-
"Function"
— the function that constructs theHTTPRequest
-
"Options"
— theOptions
the function takes (generally these correspond to the parameters the API will take)
For things that aren't implemented by the framework already there's a format to pass one's own requests:
GitHub[
{path...},
{params...},
<|headers...|>,
ops...
]
Here's an example to access the yet-unlinked gitignore endpoints :
GitHub[
{"gitignore", "templates"},
"ResultJSON"
]
(*Out:*)
<|"StatusCode"->200,"Content"->{"Actionscript","Ada","Agda","Android","AppEngine","AppceleratorTitanium","ArchLinuxPackages","Autotools","C","C++","CFWheels","CMake","CUDA","CakePHP","ChefCookbook","Clojure","CodeIgniter","CommonLisp","Composer","Concrete5","Coq","CraftCMS","D","DM","Dart","Delphi","Drupal","EPiServer","Eagle","Elisp","Elixir","Elm","Erlang","ExpressionEngine","ExtJs","Fancy","Finale","ForceDotCom","Fortran","FuelPHP","GWT","GitBook","Go","Godot","Gradle","Grails","Haskell","IGORPro","Idris","Java","Jboss","Jekyll","Joomla","Julia","KiCAD","Kohana","Kotlin","LabVIEW","Laravel","Leiningen","LemonStand","Lilypond","Lithium","Lua","Magento","Maven","Mercury","MetaProgrammingSystem","Nim","Node","OCaml","Objective-C","Opa","OracleForms","Packer","Perl","Phalcon","PlayFramework","Plone","Prestashop","Processing","PureScript","Python","Qooxdoo","Qt","R","ROS","Rails","RhodesRhomobile","Ruby","Rust","SCons","Sass","Scala","Scheme","Scrivener","Sdcc","SeamGen","SketchUp","Smalltalk","SugarCRM","Swift","Symfony","SymphonyCMS","TeX","Terraform","Textpattern","TurboGears2","Typo3","Umbraco","Unity","UnrealEngine","VVVV","VisualStudio","Waf","WordPress","Xojo","Yeoman","Yii","ZendFramework","Zephir","gcov","nanoc","opencart","stella"}|>
Here's a more complex example to hook which will create a new release:
GitHub[
{"repos", "b3m2a1", "test", "releases"},
<|
"Method" -> "Post",
"Body" ->
ExportString[{"tag_name" -> "v0.0.1", "name" -> "test"}, "JSON"],
"Headers" ->
{"Authorization" -> Automatic}
|>,
"ResultObject"
]
The github API uses an "Authorization"
header for authenticated requests. If you want to use the cached authorization that the built-in methods use you can pass:
"Authorization"->{Automatic, Automatic}
If you just want to pass your username and be prompted to enter your password pass
"Authorization"->{username, Automatic}
And finally if you want to pass your username and password directly you can do that with
"Authorization"->{username, password}
An attempt is made in the API to make authentication details and configuration details accessible. Here are a the options:
Gets configuration details (note that default config is different from what you will see here):
GitHub["GetConfig"]
(*Out:*)
<|"Username"->"b3m2a1","EncodePassword"->False,"UseKeychain"->True,"CachePassword"->True,"LockPasswordCache"->False|>
Here's what each of these parameters does:
-
"Username"
— stores the current user (if this is changed it should be done with"SetUsername"
) -
"EncodePassword"
— whether to encode passwords into aGitHubPath
object (can be used for push without SSH) -
"UseKeychain"
— whether to use the BTools$Keychain
object or not (defaults toFalse
as the keychain stores permanently) -
"CachePassword"
— whether to store passwords in the session or not -
"LockPasswordCache"
— currently unused, but will be a companion to the"LockPasswordCache"
method
GitHub["SetConfig", "UseKeychain"->False]
(*Out:*)
<|"Username"->"b3m2a1","EncodePassword"->False,"UseKeychain"->False,"CachePassword"->True,"LockPasswordCache"->False|>
GitHub["SetConfig", {"UseKeychain"->False, "LockPasswordCache"->True}]
(*Out:*)
<|"Username"->"b3m2a1","EncodePassword"->False,"UseKeychain"->False,"CachePassword"->True,"LockPasswordCache"->True|>
GitHub["CurrentUser"]
(*Out:*)
"b3m2a1"
GitHub["SetUsername", "test"]
This will open up a dialog to get the password if it doesn't have it:
GitHub["GetPassword"]
(*Out:*)
"password"
Any time a new username is provided a new password will be requested
Useful because the passwords associated to a username is cached by default
GitHub["ClearPassword", "asd"]
GitHub["SetPassword", "password"]
This provides the authorization token GitHub requires for the current user
GitHub["GetAuthorizationHeader"]
(*Out:*)
"Basic dGVzdDpwYXNzd29yZA=="
You can see how the token is constructed:
Developer`DecodeBase64@"dGVzdDpwYXNzd29yZA=="
(*Out:*)
"test:password"
There are a number of requests related to repositories. GitHub
implements everything here (and if it's missing something create an issue and it will be added).
res = GitHub["ListRepositories", "ResultObject"]
(*Out:*)

res["Result"][[1, "FullName"]]
(*Out:*)
"b3m2a1/BugTracker"
GitHub["ListRepositories", "kubaPod", "ResultObject"]
(*Out:*)

GitHub["GetRepository", "b3m2a1/BugTracker", "ResultObject"]
(*Out:*)

CreateRepository
GitHub["CreateRepository", "test", "ResultObject"]
(*Out:*)

GitHub["EditRepository",
"b3m2a1/test",
"Name"->"test",
"Description"->"a test repo",
"ResultObject"
]
(*Out:*)

GitHub["DeleteRepository", "test", "ResultObject"]
(*Out:*)

GitHub["ListContributors", "paclets/PacletServer", "ResultObject"]
(*Out:*)

GitHub["ListForks", "paclets/PacletServer", "ResultObject"]
(*Out:*)

GitHub["Fork", "kubaPod/DevTools", "ResultObject"]
(*Out:*)

Delete the fork:
GitHub["DeleteRepository", "DevTools", "ResultObject"]
(*Out:*)

rel =
GitHub["CreateRelease",
"b3m2a1/BugTracker",
"v1.0.2",
"Name"->"test",
"ResultObject"
]
(*Out:*)

GitHub["EditRelease",
"b3m2a1/BugTracker",
rel["ID"],
"Description"->"test release",
"ResultObject"
]
(*Out:*)

GitHub["DeleteRelease",
"b3m2a1/BugTracker",
rel["ID"],
"ResultObject"
]
(*Out:*)

The full listing of supported requests can be extracted from the dispatcher Association
:
BTools`External`Git`$GitHubActions//Keys
(*Out:*)
{"AddFile","BranchInfo","ClearPassword","Clone","Configure","Create","CreateBlob","CreateIssue","CreateIssueComment","CreatePullRequest","CreateReadme","CreateReference","CreateRelease","CreateRepository","CreateTag","CurrentUser","Delete","DeleteFile","DeleteIssueComment","DeleteReference","DeleteRelease","DeleteReleaseAsset","DeleteRepository","Deployments","Edit","EditFile","EditIssue","EditIssueComment","EditRelease","EditReleaseAsset","EditRepository","Fork","GetAllReferences","GetAuthorizationHeader","GetBlob","GetCommit","GetConfig","GetDirectory","GetFile","GetFileSHA","GetIssue","GetPassword","GetReadme","GetReference","GetRelease","GetReleaseAsset","GetRepository","GetTag","GetTree","ListBranches","ListContributors","ListForks","ListIssueComments","ListIssues","ListMyRepositories","ListPullRequests","ListReleaseAssets","ListRepositories","ListUserIssues","Merge","Path","PathQ","PullRequestInfo","Push","RawPath","RawURL","Releases","RepoQ","Repositories","SetConfig","SetPassword","SetUsername","SVNPath","SVNURL","UpdateReference","UploadReleaseAsset","URL"}