github: functions module for shellfire

This module provides a simple framework for using GitHub v3 REST API with a shellfire application. It currently supports a subset of features for managing releases. We welcome contributions to increase the coverage.

Compatibility

• Tag release_2015.0117.1750-1 is compatible with shellfire release release_2015.0117.1750-1.

Overview

To use the API, you first need to initialise it. We use OAuth2 Personal Access Tokens, which you can create yourself.

github_api_v3_initialise "$tokenFilePath"

tokenFilePath should be a path to a file that contains one line with an OAuth2 Personal Access Token in it. You can create these tokens using the settings for your account. On no account should you check in this file! You may want to add a rule to your .gitignore file just to make sure.

You can then make API calls. For example, to retrieve a list of release URLs:-

github_api_v3_releases_list "$owner" "$repo"

url=''
some_event_callback()
{
	if jsonreader_eventMatches ":${jsonreader_path_index}/url" string; then
		echo "Url for release is $eventValue"
	fi
}
jsonreader_parse "$github_api_v3_responseFilePath" some_event_callback

This example uses the jsonreader parser and event handler. For an example of how to handle more complex needs, see the function _github_api_v3_errorMessage_event() in the v3.functions source code.

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/github.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/github.git above if using a fork.

You will also need to add paths - include the module paths.d.

You will also need to import the [curl], urlencode, jsonreader, jsonwriter, unicode and version modules.

Namespace github_api_v3

This namespace contains the core functionality needed to access the API.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn github/api v3

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn github/api v3
	…
}

Functions

---

github_api_v3_initialise

Parameter	Value	Optional
tokenFilePath	Path to a file that contains one line with an OAuth2 Personal Access Token in it.	No
github_api_v3_endpoint	Base URL of endpoint (for GitHub Enterprise). Defaults to https://api.github.com.	Yes

Creates temporary file paths for request and response bodies in github_api_v3_responseFilePath and github_api_v3_requestFilePath (the latter can be overriden by setting curl_uploadFile).

---

github_api_v3_timestampToEpochSeconds

Parameter	Value	Optional
timestamp	Timestamp from GitHub	No

Helper function to convert GitHub timestamps into epoch seconds (ie seconds since the Unix epoch of 1970).

Namespace github_api_v3_releases

This namespace contains functionality to create releases. It is very closely linked to the underlying REST API, and you should refer to that documentation for specific meanings.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn github/api/v3 releases

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn github/api/v3 releases
	…
}

Functions

---

github_api_v3_releases_list

Parameter	Value	Optional
owner	Repository owner	No
repo	Repository	No

Returns a JSON document listing releases in github_api_v3_responseFilePath. Use the jsonreader module to parse it.

---

github_api_v3_releases_create

Parameter	Value	Optional
owner	Repository owner	No
repo	Repository	No
tagName	tag name	No
commitish	commitish	No
name	Name of this release	No
body	A non empty string of markdown	No
draft	true or false	No
prerelease	true or false	No

Creates a release.

Sets the variable github_api_v3_header_Location to the location URL of the created release. Sets the variable github_api_v3_releases_id to the release's id. Sets the variable github_api_v3_releases_uploadUrlTemplate to the upload url template for assets.

---

github_api_v3_releases_edit

Parameter	Value	Optional
owner	Repository owner	No
repo	Repository	No
id	Release id	No
tagName	tag name	No
commitish	commitish	No
name	Name of this release	No
body	A non empty string of markdown	No
draft	true or false	No
prerelease	true or false	No

Edits a release id. Other fields as for github_api_v3_releases_create.

---

github_api_v3_releases_delete

Parameter	Value	Optional
owner	Repository owner	No
repo	Repository	No
id	Release id (eg from github_api_v3_releases_list())	No

Deletes the release.

---

github_api_v3_releases_uploadAsset

Parameter	Value	Optional
uploadUrlTemplate	Repository owner	No
filePath	Path to file to upload	No
contentType	MIME Content-Type of file to upload	No
label	Human-friendly file name, effectively	No

Uploads a release asset and then changes its label using a PATCH only if the label doesn't match the basename of filePath. uploadUrlTemplate can be obtained from github_api_v3_releases_uploadUrlTemplate after a call to github_api_v3_releases_create().