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.
You should already have these details from when you setup your GitHub account.
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.
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!
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.
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.
property name="ContentService" inject="ContentService@cbgithub";
...
readme = ContentService.getReadme( owner="elpete", repo="cbgithub", ref="master", encoding="utf-8" );
| 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 |
| Property | Type | Value | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| content | string | IyBjYmdpdGh1YgoKWyFbTWFzdGVyIEJyYW5jaCBCdWlsZCBTdGF0dXNdKGh0 dHBzOi8vaW1nLnNoaWVsZHMuaW8vdHJhdmlzL2VscGV0ZS9jYmdpdGh1Yi9t YXN0ZXIuc3ZnP3N0eWxlPWZsYXQtc3F1YXJlJmxhYmVsPW1hc3RlcildKGh0 dHBzOi8vdHJhdmlzLWNpLm9yZy9lbHBldGUvY2JnaXRodWIpCgoKIyMgQSBD Rk1MIFdyYXBwZXIgYXJvdW5kIHRoZSBHaXRIdWIgQVBJIG9wdGltaXplZCBm b3IgQ29sZEJveAoKIyMgVGVzdGluZwoKVG8gcnVuIHRoZSB0ZXN0cywgZmly c3QgY29weSB0aGUgYC5lbnYuZXhhbXBsZWAgZmlsZSB0byBgLmVudmAgYW5k IGZpbGwgb3V0IHRoZSByZXF1aXJlZCBwcm9wZXJ0aWVzLiAgVGhpcyBpcyB1 c2VkIHRvIHRlc3QgYWdhaW5zdCB0aGUgYWN0dWFsIEdpdEh1YiBhcGkgd2l0 aG91dCBwZXJzaXN0aW5nIGFueSBjaGFuZ2VzLiAgQWRkaXRpb25hbGx5LCBz b21lIG9mIHRoZSB0ZXN0cyByZXF1aXJlIDItZmFjdG9yIGF1dGhlbnRpY2F0 aW9uIHRvIGJlIHR1cm5lZCBvZmYuIChEb24ndCB3b3JyeSwgd2UgZnVsbHkg c3VwcG9ydCAyLWZhY3RvciBhdXRoZW50aWNhdGlvbiEp | ||||||||||||
| _links | struct |
|
||||||||||||
| 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 |
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.
property name="ContentService" inject="ContentService@cbgithub";
...
file = ContentService.read( owner="elpete", repo="cbgithub", path="models/Content.cfc", ref="master", encoding="utf-8" );
| 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 |
| Property | Type | Value |
|---|---|---|
| content | string | JyYW5jaCBCdWlsZCBTdGF0dXNdKGh0IyBjYmdpdGh1YgoKWyFbTWFzdGVyIE YXN0ZXIuc3ZnP3N0eWxlPWZsYXQtc3F1YXJlJmxhYmVsPW1hc3RlcildKGh0 dHBzOi8vdHJhdmlzLWNpLm9yZy9lbHBldGUvY2JnaXRodWIpCgoKIyMgQSBD aG91dCBwZXJzaXN0aW5nIGFueSBjaGFuZ2VzLiAgQWRkaXRpb25hbGx5LCBz Rk1MIFdyYXBwZXIgYXJvdW5kIHRoZSBHaXRIdWIgQVBJIG9wdGltaXplZCBm dHBzOi8vaW1nLnNoaWVsZHMuaW8vdHJhdmlzL2VscGV0ZS9jYmdpdGh1Yi9t c3QgY29weSB0aGUgYC5lbnYuZXhhbXBsZWAgZmlsZSB0byBgLmVudmAgYW5k b3IgQ29sZEJveAoKIyMgVGVzdGluZwoKVG8gcnVuIHRoZSB0ZXN0cywgZmly IGZpbGwgb3V0IHRoZSByZXF1aXJlZCBwcm9wZXJ0aWVzLiAgVGhpcyBpcyB1 c2VkIHRvIHRlc3QgYWdhaW5zdCB0aGUgYWN0dWFsIEdpdEh1YiBhcGkgd2l0 aW9uIHRvIGJlIHR1cm5lZCBvZmYuIChEb24ndCB3b3JyeSwgd2UgZnVsbHkg b21lIG9mIHRoZSB0ZXN0cyByZXF1aXJlIDItZmFjdG9yIGF1dGhlbnRpY2F0 XRoZW50aWNhdGlvbiEpc3VwcG9ydCAyLWZhY3RvciBhd |
| _links | struct | |
| 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 |
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!)
This project has been tested against Adobe ColdFusion 11+ and Lucee 4.5+ servers.
Thanks goes to these wonderful people (emoji key):
 Eric Peterson 💬 💻 📖 |
 Richard Herbert 💻 📖 |
|---|
This project follows the all-contributors specification. Contributions of any kind welcome!