cbgithub

A CFML Wrapper around the GitHub API optimized for ColdBox

Getting Started

Access Security

There are two ways of providing secure access to your GitHub repository: Username and password or Personal Access Token. If both are provided, the Personal Access Token is used.

Username and Password

You should already have these details from when you setup your GitHub account.

Personal Access Token

A Personal Access Token is generated from within your GitHub Account online.

First sign in to your GitHub Account using your username or email address and password. Then, from your account (top right dropdown), select Settings then Personal access token under Developer settings. Select Generate new token and provide a Token description such as cbgithub. Choose the Select scopes that are appropriate for the access you need to this GitHub account. If you want to create, update or delete content you will have to have enable public_repo as a minimum. Make a note of the new personal access token generated.

Configuring cbgithub Security

Now you need to take either your GitHub username and password or the personal access token you've just created and add them to your ColdBox Module settings in config/Coldbox.cfc. Take a look at Retrieving Module Settings for more information.

Populate your config/Coldbox.cfc like this if you want to use your username and password...

moduleSettings = {
    cbgithub = {
        "username" = "myUserName",
        "password" = "myPassword"
    }
};

...or like this if you want to use your personal access token...

moduleSettings = {
    cbgithub = {
        "token" = "myPersonalToken"
    }
};

Remember: Don't commit these details to a publicly accessible GitHub repository otherwise your account could be compromised!

Contents Endpoint

GitHub offers a set of endpoints that provide access to the contents of files in the repository. These include the ability to read the README file and any other file. Also it's possible to create, update and delete any file in the repository.

getReadme( owner, repo, ref, encoding )

I return a Content object populated with information about the README file. Calling the getContent() method on the Content object will decode the raw base64 string.

Example

property name="ContentService" inject="ContentService@cbgithub";

...

readme = ContentService.getReadme( owner="elpete", repo="cbgithub", ref="master", encoding="utf-8" );

Arguments

Argument	Description
owner (required, string)	Name of the GitHub account
repo (required, string)	Name of the repository of the owner
ref (optional, string="master")	Name of the branch, tag or commit to read from
encoding (optional, string="utf-8")	Type of file encoding

Response

Property	Type	Value
content	string	IyBjYmdpdGh1YgoKWyFbTWFzdGVyIEJyYW5jaCBCdWlsZCBTdGF0dXNdKGh0 dHBzOi8vaW1nLnNoaWVsZHMuaW8vdHJhdmlzL2VscGV0ZS9jYmdpdGh1Yi9t YXN0ZXIuc3ZnP3N0eWxlPWZsYXQtc3F1YXJlJmxhYmVsPW1hc3RlcildKGh0 dHBzOi8vdHJhdmlzLWNpLm9yZy9lbHBldGUvY2JnaXRodWIpCgoKIyMgQSBD Rk1MIFdyYXBwZXIgYXJvdW5kIHRoZSBHaXRIdWIgQVBJIG9wdGltaXplZCBm b3IgQ29sZEJveAoKIyMgVGVzdGluZwoKVG8gcnVuIHRoZSB0ZXN0cywgZmly c3QgY29weSB0aGUgYC5lbnYuZXhhbXBsZWAgZmlsZSB0byBgLmVudmAgYW5k IGZpbGwgb3V0IHRoZSByZXF1aXJlZCBwcm9wZXJ0aWVzLiAgVGhpcyBpcyB1 c2VkIHRvIHRlc3QgYWdhaW5zdCB0aGUgYWN0dWFsIEdpdEh1YiBhcGkgd2l0 aG91dCBwZXJzaXN0aW5nIGFueSBjaGFuZ2VzLiAgQWRkaXRpb25hbGx5LCBz b21lIG9mIHRoZSB0ZXN0cyByZXF1aXJlIDItZmFjdG9yIGF1dGhlbnRpY2F0 aW9uIHRvIGJlIHR1cm5lZCBvZmYuIChEb24ndCB3b3JyeSwgd2UgZnVsbHkg c3VwcG9ydCAyLWZhY3RvciBhdXRoZW50aWNhdGlvbiEp
_links	struct	Property Type Value html string https://github.com/elpete/cbgithub/blob/master/README.md self string https://api.github.com/repos/elpete/cbgithub/contents/README.md?ref=master git string https://api.github.com/repos/elpete/cbgithub/git/blobs/6b029017cb3349add550d491729e435d7cafa7d3
html_url	string	https://github.com/elpete/cbgithub/blob/master/README.md
sha	string	6b029017cb3349add550d491729e435d7cafa7d3
path	string	README.md
url	string	https://api.github.com/repos/elpete/cbgithub/contents/README.md?ref=master
size	number	573
name	string	README.md
submodule_git_url	string
type	string	file
git_url	string	https://api.github.com/repos/elpete/cbgithub/git/blobs/6b029017cb3349add550d491729e435d7cafa7d3
download_url	string	https://raw.githubusercontent.com/elpete/cbgithub/master/README.md
encoding	string	base64
mimetype	string	text/plain

read( owner, repo, path, ref, encoding )

I return a Content object populated with information about the requested file. Calling the getContent() method on the Content object will decode the raw base64 string if it is has the mime type of text/plain.

Example

property name="ContentService" inject="ContentService@cbgithub";

...

file = ContentService.read( owner="elpete", repo="cbgithub", path="models/Content.cfc", ref="master", encoding="utf-8" );

Arguments

Argument	Description
owner (required, string)	Name of the GitHub account
repo (required, string)	Name of the repository of the owner
path (required, string)	File pathname of the file to retrieve
ref (optional, string="master")	Name of the branch, tag or commit to read from
encoding (optional, string="utf-8")	Type of file encoding

Response

Property	Type	Value
content	string	JyYW5jaCBCdWlsZCBTdGF0dXNdKGh0IyBjYmdpdGh1YgoKWyFbTWFzdGVyIE YXN0ZXIuc3ZnP3N0eWxlPWZsYXQtc3F1YXJlJmxhYmVsPW1hc3RlcildKGh0 dHBzOi8vdHJhdmlzLWNpLm9yZy9lbHBldGUvY2JnaXRodWIpCgoKIyMgQSBD aG91dCBwZXJzaXN0aW5nIGFueSBjaGFuZ2VzLiAgQWRkaXRpb25hbGx5LCBz Rk1MIFdyYXBwZXIgYXJvdW5kIHRoZSBHaXRIdWIgQVBJIG9wdGltaXplZCBm dHBzOi8vaW1nLnNoaWVsZHMuaW8vdHJhdmlzL2VscGV0ZS9jYmdpdGh1Yi9t c3QgY29weSB0aGUgYC5lbnYuZXhhbXBsZWAgZmlsZSB0byBgLmVudmAgYW5k b3IgQ29sZEJveAoKIyMgVGVzdGluZwoKVG8gcnVuIHRoZSB0ZXN0cywgZmly IGZpbGwgb3V0IHRoZSByZXF1aXJlZCBwcm9wZXJ0aWVzLiAgVGhpcyBpcyB1 c2VkIHRvIHRlc3QgYWdhaW5zdCB0aGUgYWN0dWFsIEdpdEh1YiBhcGkgd2l0 aW9uIHRvIGJlIHR1cm5lZCBvZmYuIChEb24ndCB3b3JyeSwgd2UgZnVsbHkg b21lIG9mIHRoZSB0ZXN0cyByZXF1aXJlIDItZmFjdG9yIGF1dGhlbnRpY2F0 XRoZW50aWNhdGlvbiEpc3VwcG9ydCAyLWZhY3RvciBhd
_links	struct	Property Type Value html string https://github.com/elpete/cbgithub/blob/master/models/Content.cfc self string https://api.github.com/repos/elpete/cbgithub/contents/models/Content.cfc?ref=master git string https://api.github.com/repos/elpete/cbgithub/git/blobs/8d1a3dd6c0c4ae7de4bb4f9cbaf2e4b54fda3fa6
html_url	string	https://github.com/elpete/cbgithub/blob/master/models/Content.cfc
sha	string	8d1a3dd6c0c4ae7de4bb4f9cbaf2e4b54fda3fa6
path	string	models/Content.cfc
url	string	https://api.github.com/repos/elpete/cbgithub/contents/models/Content.cfc?ref=master
size	number	2335
name	string	Content.cfc
submodule_git_url	string
type	string	file
git_url	string	https://api.github.com/repos/elpete/cbgithub/git/blobs/8d1a3dd6c0c4ae7de4bb4f9cbaf2e4b54fda3fa6
download_url	string	https://raw.githubusercontent.com/elpete/cbgithub/master/models/Content.cfc
encoding	string	base64
mimetype	string	text/plain

Testing

To run the tests, first copy the .env.example file to .env and fill out the required properties. This is used to test against the actual GitHub api without persisting any changes. Additionally, some of the tests require 2-factor authentication to be turned off. (Don't worry, we fully support 2-factor authentication!)

Compatibility

This project has been tested against Adobe ColdFusion 11+ and Lucee 4.5+ servers.

Contributors

Thanks goes to these wonderful people (emoji key):

Eric Peterson 💬 💻 📖 ⚠️	Richard Herbert 💻 📖 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!