- [Build your own Octokit with Plugins and Defaults](#build-your-own-octokit-with-plugins-and-defaults)
- [LICENSE](#license)
<!-- tocstop -->
If you need a minimalistic library to utilize GitHub's [REST API](https://developer.github.com/v3/) and [GraphQL API](https://developer.github.com/v4/) which you can extend with plugins as needed, then `@octokit/core` is a great starting point.
If you don't need the Plugin API then using [`@octokit/request`](https://github.com/octokit/request.js/) or [`@octokit/graphql`](https://github.com/octokit/graphql.js/) directly is a good alternative.
## Usage
<table>
<tbodyvalign=topalign=left>
<tr><th>
Browsers
</th><tdwidth=100%>
Load <code>@octokit/core</code> directly from <ahref="https://cdn.skypack.dev">cdn.skypack.dev</a>
```html
<scripttype="module">
import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
</script>
```
</td></tr>
<tr><th>
Node
</th><td>
Install with <code>npm install @octokit/core</code>
```js
const { Octokit } = require("@octokit/core");
// or: import { Octokit } from "@octokit/core";
```
</td></tr>
</tbody>
</table>
### REST API example
```js
// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit({ auth: `personal-access-token123` });
See [`@octokit/request`](https://github.com/octokit/request.js) for full documentation of the `.request` method.
### GraphQL example
```js
const octokit = new Octokit({ auth: `secret123` });
const response = await octokit.graphql(
`query ($login: String!) {
organization(login: $login) {
repositories(privacy: PRIVATE) {
totalCount
}
}
}`,
{ login: "octokit" }
);
```
See [`@octokit/graphql`](https://github.com/octokit/graphql.js) for full documentation of the `.graphql` method.
## Options
<table>
<theadalign=left>
<tr>
<th>
name
</th>
<th>
type
</th>
<thwidth=100%>
description
</th>
</tr>
</thead>
<tbodyalign=leftvalign=top>
<tr>
<th>
<code>options.authStrategy</code>
</th>
<td>
<code>Function<code>
</td>
<td>
Defaults to <ahref="https://github.com/octokit/auth-token.js#readme"><code>@octokit/auth-token</code></a>. See <ahref="#authentication">Authentication</a> below for examples.
</td>
</tr>
<tr>
<th>
<code>options.auth</code>
</th>
<td>
<code>String</code> or <code>Object</code>
</td>
<td>
See <ahref="#authentication">Authentication</a> below for examples.
</td>
</tr>
<tr>
<th>
<code>options.baseUrl</code>
</th>
<td>
<code>String</code>
</td>
<td>
When using with GitHub Enterprise Server, set `options.baseUrl` to the root URL of the API. For example, if your GitHub Enterprise Server's hostname is `github.acme-inc.com`, then set `options.baseUrl` to `https://github.acme-inc.com/api/v3`. Example
```js
const octokit = new Octokit({
baseUrl: "https://github.acme-inc.com/api/v3",
});
```
</td></tr>
<tr>
<th>
<code>options.previews</code>
</th>
<td>
<code>Array of Strings</code>
</td>
<td>
Some REST API endpoints require preview headers to be set, or enable
additional features. Preview headers can be set on a per-request basis, e.g.
You can also set previews globally, by setting the `options.previews` option on the constructor. Example:
```js
const octokit = new Octokit({
previews: ["shadow-cat"],
});
```
</td></tr>
<tr>
<th>
<code>options.request</code>
</th>
<td>
<code>Object</code>
</td>
<td>
Set a default request timeout (`options.request.timeout`) or an [`http(s).Agent`](https://nodejs.org/api/http.html#http_class_http_agent) e.g. for proxy usage (Node only, `options.request.agent`).
There are more `options.request.*` options, see [`@octokit/request` options](https://github.com/octokit/request.js#request). `options.request` can also be set on a per-request basis.
</td></tr>
<tr>
<th>
<code>options.timeZone</code>
</th>
<td>
<code>String</code>
</td>
<td>
Sets the `Time-Zone` header which defines a timezone according to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
```js
const octokit = new Octokit({
timeZone: "America/Los_Angeles",
});
```
The time zone header will determine the timezone used for generating the timestamp when creating commits. See [GitHub's Timezones documentation](https://developer.github.com/v3/#timezones).
</td></tr>
<tr>
<th>
<code>options.userAgent</code>
</th>
<td>
<code>String</code>
</td>
<td>
A custom user agent string for your app or library. Example
```js
const octokit = new Octokit({
userAgent: "my-app/v1.2.3",
});
```
</td></tr>
</tbody>
</table>
## Defaults
You can create a new Octokit class with customized default options.
```js
const MyOctokit = Octokit.defaults({
auth: "personal-access-token123",
baseUrl: "https://github.acme-inc.com/api/v3",
userAgent: "my-app/v1.2.3",
});
const octokit1 = new MyOctokit();
const octokit2 = new MyOctokit();
```
If you pass additional options to your new constructor, the options will be merged shallowly.
```js
const MyOctokit = Octokit.defaults({
foo: {
opt1: 1,
},
});
const octokit = new MyOctokit({
foo: {
opt2: 1,
},
});
// options will be { foo: { opt2: 1 }}
```
If you need a deep or conditional merge, you can pass a function instead.
```js
const MyOctokit = Octokit.defaults((options) => {
return {
foo: Object.assign({}, options.foo, { opt2: 1 }),
};
});
const octokit = new MyOctokit({
foo: { opt2: 1 },
});
// options will be { foo: { opt1: 1, opt2: 1 }}
```
Be careful about mutating the `options` object in the `Octokit.defaults` callback, as it can have unforeseen consequences.
## Authentication
Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your [API rate limit](https://developer.github.com/v3/#rate-limiting).
By default, Octokit authenticates using the [token authentication strategy](https://github.com/octokit/auth-token.js). Pass in a token using `options.auth`. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The `Authorization` header will be set according to the type of token.
```js
import { Octokit } from "@octokit/core";
const octokit = new Octokit({
auth: "mypersonalaccesstoken123",
});
const { data } = await octokit.request("/user");
```
To use a different authentication strategy, set `options.authStrategy`. A list of authentication strategies is available at [octokit/authentication-strategies.js](https://github.com/octokit/authentication-strategies.js/#readme).
Example
```js
import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: {
appId: 123,
privateKey: process.env.PRIVATE_KEY,
},
});
const { data } = await appOctokit.request("/app");
```
The `.auth()` method returned by the current authentication strategy can be accessed at `octokit.auth()`. Example
```js
const { token } = await appOctokit.auth({
type: "installation",
installationId: 123,
});
```
## Logging
There are four built-in log methods
1.`octokit.log.debug(message[, additionalInfo])`
1.`octokit.log.info(message[, additionalInfo])`
1.`octokit.log.warn(message[, additionalInfo])`
1.`octokit.log.error(message[, additionalInfo])`
They can be configured using the [`log` client option](client-options). By default, `octokit.log.debug()` and `octokit.log.info()` are no-ops, while the other two call `console.warn()` and `console.error()` respectively.
This is useful if you build reusable [plugins](#plugins).
If you would like to make the log level configurable using an environment variable or external option, we recommend the [console-log-level](https://github.com/watson/console-log-level) package. Example
## Build your own Octokit with Plugins and Defaults
You can build your own Octokit class with preset default options and plugins. In fact, this is mostly how the `@octokit/<context>` modules work, such as [`@octokit/action`](https://github.com/octokit/action.js):
