Skip to content
b3m2a1 edited this page Dec 11, 2018 · 4 revisions

GitHub Examples

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 .

General Form

A request is generally formatted like so:

GitHub["Name", params...]

You can also specify a return format. These can be any of

  • "HTTPRequest" — the HTTPRequest to be passed

  • "HTTPResponse" — the HTTPResponse returned

  • "ResultJSON" — the result imported as "JSON"

  • "ImportedResult" — the JSON result imported as formatted Association . This is default return format.

  • "ResultObject" — the result imported as "ResultObject" ( Success or Failure )

There are also two special parameters that may be requested in place of the params :

  • "Function" — the function that constructs the HTTPRequest

  • "Options" — the Options the function takes (generally these correspond to the parameters the API will take)

Direct API Access

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"
 ]

Authorization

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}

Authentication and Configuration

An attempt is made in the API to make authentication details and configuration details accessible. Here are a the options:

GetConfig

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 a GitHubPath object (can be used for push without SSH)

  • "UseKeychain" — whether to use the BTools $Keychain object or not (defaults to False 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

SetConfig

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|>

CurrentUser

GitHub["CurrentUser"]
(*Out:*)

"b3m2a1"

SetUsername

GitHub["SetUsername", "test"]

GetPassword

This will open up a dialog to get the password if it doesn't have it:

GitHub["GetPassword"]

github-1874608336607830462

(*Out:*)

"password"

Any time a new username is provided a new password will be requested

ClearPassword

Useful because the passwords associated to a username is cached by default

GitHub["ClearPassword", "asd"]

SetPassword

GitHub["SetPassword", "password"]

GetAuthorizationHeader

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"

Repositories

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).

ListRepositories

res = GitHub["ListRepositories", "ResultObject"]

(*Out:*)


 

github-4479466270502396487

res["Result"][[1, "FullName"]]
(*Out:*)

"b3m2a1/BugTracker"
GitHub["ListRepositories", "kubaPod", "ResultObject"]

(*Out:*)


 

github-8941333856016630695

GetRepository

GitHub["GetRepository", "b3m2a1/BugTracker", "ResultObject"]

(*Out:*)


 

github-756638439692915082

CreateRepository

GitHub["CreateRepository", "test", "ResultObject"]

(*Out:*)


 

github-4922254358508617453

EditRepository

GitHub["EditRepository", 
  "b3m2a1/test", 
  "Name"->"test", 
  "Description"->"a test repo",
  "ResultObject"
  ]

(*Out:*)


 

github-273489049608989970

DeleteRepository

GitHub["DeleteRepository", "test", "ResultObject"]

(*Out:*)


 

github-7772922015420866670

ListContributors

GitHub["ListContributors", "paclets/PacletServer", "ResultObject"]

(*Out:*)


 

github-5705547431485621005

Forks

ListForks

GitHub["ListForks", "paclets/PacletServer", "ResultObject"]

(*Out:*)


 

github-2421180881204356391

CreateFork

GitHub["Fork", "kubaPod/DevTools", "ResultObject"]

(*Out:*)


 

github-2839330886057410087

Delete the fork:

GitHub["DeleteRepository", "DevTools", "ResultObject"]

(*Out:*)


 

github-7772922015420866670

Releases

CreateRelease

rel =
  GitHub["CreateRelease", 
    "b3m2a1/BugTracker",
    "v1.0.2", 
    "Name"->"test",
    "ResultObject"
    ]

(*Out:*)


 

github-7778441936909920135

EditRelease

GitHub["EditRelease", 
  "b3m2a1/BugTracker",
  rel["ID"],
  "Description"->"test release",
  "ResultObject"
  ]

(*Out:*)


 

github-8442215317818773729

DeleteRelease

GitHub["DeleteRelease", 
  "b3m2a1/BugTracker",
  rel["ID"],
  "ResultObject"
  ]

(*Out:*)


 

github-1444829963234262499

Full Listing

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"}
Clone this wiki locally