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
You can set options.auth
to a token, which will be used to correctly set the Authorization
header for the requests you do with octokit.request()
and octokit.graphql()
. Example
import { Octokit } from "@octokit/core";
const octokit = new Octokit({
auth: "mypersonalaccesstoken123"
});
octokit.request("/user").then(response => console.log(response.data));
All other authentication strategies are supported using @octokit/auth
, just pass the auth()
method returned by any of the strategies as options.auth
. Example
import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";
const octokit = new Octokit({
auth: createAppAuth({
id: 123,
privateKey: process.env.PRIVATE_KEY
)}
})
octokit.request('/app').then(response => console.log(response.data))
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.
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.helloWorld = () => console.log(`${options.greeting}, world!`);
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;
});
};
LICENSE
MIT