What is @octokit/core?
The @octokit/core package is a core library for GitHub's REST API v3. It provides a simplified interface to interact with GitHub's API, allowing developers to authenticate, send requests, and process responses. This package is part of the Octokit SDK, which is a collection of libraries for working with the GitHub API.
What are @octokit/core's main functionalities?
Authentication
Authenticate with the GitHub API using a personal access token. This is essential for performing actions that require GitHub permissions.
{
const { Octokit } = require('@octokit/core');
const octokit = new Octokit({ auth: `personal_access_token` });
}
Send Requests
Send requests to the GitHub API. This example fetches a user's profile information using their username.
{
const { Octokit } = require('@octokit/core');
const octokit = new Octokit();
async function fetchUser() {
const response = await octokit.request('GET /users/{username}', {
username: 'octocat'
});
console.log(response.data);
}
fetchUser();
}
Custom Requests
Create custom requests to perform specific actions, such as creating an issue in a repository. This demonstrates how to use the package to interact with various parts of the GitHub API.
{
const { Octokit } = require('@octokit/core');
const octokit = new Octokit();
async function createIssue(owner, repo, title, body) {
const response = await octokit.request('POST /repos/{owner}/{repo}/issues', {
owner,
repo,
title,
body
});
console.log(response.data);
}
createIssue('octocat', 'Hello-World', 'New issue title', 'Issue body content');
}
Other packages similar to @octokit/core
github
The 'github' package is a Node.js wrapper for the GitHub API. It offers similar functionalities to @octokit/core but is less modular and not as actively maintained. @octokit/core benefits from being part of the larger Octokit SDK, which provides more comprehensive tools and a consistent API design.
node-github
Similar to 'github', 'node-github' is another wrapper for the GitHub API designed for Node.js. It provides access to the GitHub API but lacks the modularity and extensibility of @octokit/core. The Octokit libraries, including @octokit/core, are officially maintained by GitHub, offering better support and integration with GitHub's evolving API.
core.js
Extendable client for GitHub's REST & GraphQL APIs
If you need a minimalistic library to utilize GitHub's REST API and GraphQL API which you can extend with plugins as needed, than @octokit/core
is a great starting point.
If you don't need the Plugin API then using @octokit/request
or @octokit/graphql
directly is a good alternative.
Usage
Browsers
|
Load @octokit/core directly from cdn.pika.dev
<script type="module">
import { Octokit } from "https://cdn.pika.dev/@octokit/core";
</script>
|
---|
Node
|
Install with npm install @octokit/core
const { Octokit } = require("@octokit/core");
|
---|
REST API example
const octokit = new Octokit({ auth: `personal-access-token123` });
const response = await octokit.request("GET /orgs/:org/repos", {
org: "octokit",
type: "private"
});
See @octokit/request
for full documentation of the .request
method.
GraphQL example
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
name
|
type
|
description
|
---|
options.auth
|
String or @octokit/auth instance
|
If set to a String , then it's expected to be a personal access token or OAuth access token and used accordingly in the Authorization header.
For all other authentication strategies, set options.auth to a @octokit/auth instance.
See Authentication below for examples.
|
---|
options.baseUrl
|
String
|
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
const octokit = new Octokit({
baseUrl: "https://github.acme-inc.com/api/v3"
});
|
---|
options.previews
|
Array of Strings
|
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.
octokit.request("POST /repos/:owner/:repo/pulls", {
mediaType: {
previews: ["shadow-cat"]
},
owner,
repo,
title: "My pull request",
base: "master",
head: "my-feature",
draft: true
});
You can also set previews globally, by setting the options.previews option on the constructor. Example:
const octokit = new Octokit({
previews: ["shadow-cat"]
});
|
---|
options.request
|
Object
|
Set a default request timeout (options.request.timeout ) or an http(s).Agent e.g. for proxy usage (Node only, options.request.agent ).
There are more options.request.* options, see @octokit/request options. options.request can also be set on a per-request basis.
|
---|
options.userAgent
|
String
|
A custom user agent string for your app or library. Example
const octokit = new Octokit({
userAgent: "my-app/v1.2.3"
});
|
---|
Defaults
You can create a new Octokit class with customized default options.
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();
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.
By default, Octokit authenticates using the token authentication strategy. 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.
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 set of officially supported authentication strategies can be retrieved from @octokit/auth
. Example
import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: {
id: 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
const { token } = await appOctokit.auth({
type: "installation",
installationId: 123
});
Logging
There are four built-in log methods
octokit.log.debug(message[, additionalInfo])
octokit.log.info(message[, additionalInfo])
octokit.log.warn(message[, additionalInfo])
octokit.log.error(message[, additionalInfo])
They can be configured using the log
client option. 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.
If you would like to make the log level configurable using an environment variable or external option, we recommend the console-log-level package. Example
const octokit = new Octokit({
log: require("console-log-level")({ level: "info" })
});
Hooks
You can customize Octokit's request lifecycle with hooks.
octokit.hook.before("request", async options => {
validate(options);
});
octokit.hook.after("request", async (response, options) => {
console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
if (error.status === 304) {
return findInCache(error.headers.etag);
}
throw error;
});
octokit.hook.wrap("request", async (request, options) => {
return request(options);
});
See before-after-hook for more documentation on hooks.
Plugins
Octokit’s functionality can be extended using plugins. THe Octokit.plugin()
method accepts a function or an array of functions and returns a new constructor.
A plugin is a function which gets two arguments:
- the current instance
- the options passed to the constructor.
In order to extend octokit
's API, the plugin must return an object with the new methods.
const MyOctokit = require("@octokit/core").plugin([
require("./lib/my-plugin"),
require("octokit-plugin-example")
]);
const octokit = new MyOctokit({ greeting: "Moin moin" });
octokit.helloWorld();
octokit.request("GET /");
module.exports = (octokit, options = { greeting: "Hello" }) => {
octokit.hook.wrap("request", async (request, options) => {
const time = Date.now();
const response = await request(options);
console.log(
`${options.method} ${options.url} – ${response.status} in ${Date.now() -
time}ms`
);
return response;
});
return {
helloWorld: () => console.log(`${options.greeting}, world!`);
}
};
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
:
const MyActionOctokit = require("@octokit/core")
.plugin([
require("@octokit/plugin-paginate"),
require("@octokit/plugin-throttle"),
require("@octokit/plugin-retry")
])
.defaults({
authStrategy: require("@octokit/auth-action"),
userAgent: `my-octokit-action/v1.2.3`
});
const octokit = new MyActionOctokit();
const installations = await octokit.paginate("GET /app/installations");
LICENSE
MIT