/github

GitHub API v3 functions module for shellfire

OtherNOASSERTION

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

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