1 | # Maintainers wanted
|
2 | [Apply within](https://github.com/github-tools/github/issues/539)
|
3 |
|
4 | # Github.js
|
5 |
|
6 | [![Downloads per month](https://img.shields.io/npm/dm/github-api.svg?maxAge=2592000)][npm-package]
|
7 | [![Latest version](https://img.shields.io/npm/v/github-api.svg?maxAge=3600)][npm-package]
|
8 | [![Gitter](https://img.shields.io/gitter/room/github-tools/github.js.svg?maxAge=2592000)][gitter]
|
9 | [![Travis](https://img.shields.io/travis/github-tools/github.svg?maxAge=60)][travis-ci]
|
10 | [![Codecov](https://img.shields.io/codecov/c/github/github-tools/github.svg?maxAge=2592000)][codecov]
|
11 |
|
12 | `Github.js` provides a minimal higher-level wrapper around Github's API.
|
13 |
|
14 | ## Usage
|
15 |
|
16 | ```javascript
|
17 | /*
|
18 | Data can be retrieved from the API either using callbacks (as in versions < 1.0)
|
19 | or using a new promise-based API. The promise-based API returns the raw Axios
|
20 | request promise.
|
21 | */
|
22 | import GitHub from 'github-api';
|
23 |
|
24 | // unauthenticated client
|
25 | const gh = new GitHub();
|
26 | let gist = gh.getGist(); // not a gist yet
|
27 | gist.create({
|
28 | public: true,
|
29 | description: 'My first gist',
|
30 | files: {
|
31 | "file1.txt": {
|
32 | content: "Aren't gists great!"
|
33 | }
|
34 | }
|
35 | }).then(function({data}) {
|
36 | // Promises!
|
37 | let createdGist = data;
|
38 | return gist.read();
|
39 | }).then(function({data}) {
|
40 | let retrievedGist = data;
|
41 | // do interesting things
|
42 | });
|
43 | ```
|
44 |
|
45 | ```javascript
|
46 | var GitHub = require('github-api');
|
47 |
|
48 | // basic auth
|
49 | var gh = new GitHub({
|
50 | username: 'FOO',
|
51 | password: 'NotFoo'
|
52 | /* also acceptable:
|
53 | token: 'MY_OAUTH_TOKEN'
|
54 | */
|
55 | });
|
56 |
|
57 | var me = gh.getUser(); // no user specified defaults to the user for whom credentials were provided
|
58 | me.listNotifications(function(err, notifications) {
|
59 | // do some stuff
|
60 | });
|
61 |
|
62 | var clayreimann = gh.getUser('clayreimann');
|
63 | clayreimann.listStarredRepos(function(err, repos) {
|
64 | // look at all the starred repos!
|
65 | });
|
66 | ```
|
67 |
|
68 | ## API Documentation
|
69 |
|
70 | [API documentation][docs] is hosted on github pages, and is generated from JSDoc; any contributions
|
71 | should include updated JSDoc.
|
72 |
|
73 | ## Installation
|
74 | `Github.js` is available from `npm` or [unpkg][unpkg].
|
75 |
|
76 | ```shell
|
77 | npm install github-api
|
78 | ```
|
79 |
|
80 | ```html
|
81 | <!-- just github-api source (5.3kb) -->
|
82 | <script src="https://unpkg.com/github-api/dist/GitHub.min.js"></script>
|
83 |
|
84 | <!-- standalone (20.3kb) -->
|
85 | <script src="https://unpkg.com/github-api/dist/GitHub.bundle.min.js"></script>
|
86 | ```
|
87 |
|
88 | ## Compatibility
|
89 | `Github.js` is tested on node's LTS and current versions.
|
90 |
|
91 | [codecov]: https://codecov.io/github/github-tools/github?branch=master
|
92 | [docs]: http://github-tools.github.io/github/
|
93 | [gitter]: https://gitter.im/github-tools/github
|
94 | [npm-package]: https://www.npmjs.com/package/github-api/
|
95 | [unpkg]: https://unpkg.com/github-api/
|
96 | [travis-ci]: https://travis-ci.org/github-tools/github
|
97 |
|
98 | ## Contributing
|
99 |
|
100 | We welcome contributions of all types! This section will guide you through setting up your development environment.
|
101 |
|
102 | ### Setup
|
103 |
|
104 | 1. [Install Node](https://nodejs.org/en/) version 8,10 or 11. It can often help to use a Node version switcher such as [NVM](https://github.com/nvm-sh/nvm).
|
105 | 2. Fork this repo to your GitHub account.
|
106 | 3. Clone the fork to your development machine (`git clone https://github.com/{YOUR_USERNAME}/github`).
|
107 | 4. From the root of the cloned repo, run `npm install`.
|
108 | 5. Email jaredrewerts@gmail.com with the subject **GitHub API - Personal Access Token Request**
|
109 |
|
110 | A personal access token for our test user, @github-tools-test, will be generated for you.
|
111 |
|
112 | 6. Set the environment variable `GHTOOLS_USER` to `github-tools-test`.
|
113 |
|
114 | `export GHTOOLS_USER=github-tools-test`
|
115 |
|
116 | 7. Set the environment variable `GHTOOLS_PASSWORD` to the personal access token that was generated for you.
|
117 |
|
118 | `export GHTOOLS_PASSWORD={YOUR_PAT}`
|
119 |
|
120 | **NOTE** Windows users can use [this guide](http://www.dowdandassociates.com/blog/content/howto-set-an-environment-variable-in-windows-command-line-and-registry/) to learn about setting environment variables on Windows.
|
121 |
|
122 | ### Tests
|
123 |
|
124 | The main way we write code for `github-api` is using test-driven development. We use Mocha to run our tests. Given that the bulk of this library is just interacting with GitHub's API, nearly all of our tests are integration tests.
|
125 |
|
126 | To run the test suite, run `npm run test`.
|