simple-octokit

Preconfigured GitHub API client with GraphQL and REST. Bundles common @octokit plugins into a simple factory function.

Table of Contents

Click to expand

• Highlights ✨
• Usage
• API
  • octokit = simpleOctokit([options])
  • octokit.graphql(query[, variables])
  • octokit[scope][method]()
  • octokit.request(route, options)
• Usage In Actions
• Install
• License

Highlights ✨

• Typical usage requires only a single option
• Builtin retry (for network errors and rate limiting)
• Includes REST (until GraphQL has full coverage) with automatic pagination
• Suitable for use in Actions like @actions/github, but not only in Actions
• Respects HTTP(S)_PROXY and NO_PROXY (and lowercase equivalents).

Usage

const simpleOctokit = require('simple-octokit')
const octokit = simpleOctokit('my-github-token')

Query the GitHub GraphQL API:

const { createIssue } = await octokit.graphql(`
  mutation($repositoryId:ID!, $title:String!) {
    createIssue(input: { repositoryId: $repositoryId, title: $title }) {
      issue { number }
    }
  }`,
  { repositoryId, title }
)

console.log(createIssue.issue.number)

Query the GitHub REST API:

const response = await octokit.issues.listForRepo({
  owner: 'octocat',
  repo: 'hello-world',
  per_page: 100
})

for (const issue of response.data) {
  console.log(issue.number)
}

The above example only fetches the first page of 100 issues. Lazily fetch all pages using for await...of:

const iterable = octokit.issues.listForRepo.all({
  owner: 'octocat',
  repo: 'hello-world',
  per_page: 100
})

for await (const response of iterable) {
  for (const issue of response.data) {
    console.log(issue.number)
  }
}

API

octokit = simpleOctokit([options])

The options argument can be a string as a shorthand for { auth } or an object with:

• auth (string): personal access token, defaults to GITHUB_TOKEN environment variable. Can also be an object to be combined with a custom authStrategy.
• keepAlive (boolean): reuse connections between requests, defaults to false
• baseUrl (string): defaults to GITHUB_API_URL environment variable or https://api.github.com
• userAgent (string): defaults to simple-octokit/${version}.

Other options are forwarded to @octokit/core.

octokit.graphql(query[, variables])

Query the GitHub GraphQL API. Takes a query string and an optional variables object. Returns a promise for the query result. It's recommended to use variables rather than template literals as those would make your code vulnerable to query injection attacks. The variables object can also contain custom request headers. For example to enable the deletePackageVersion mutation which is in preview at the time of writing:

const { deletePackageVersion } = await octokit.graphql(`
  mutation ($id: String!) {
    deletePackageVersion(input:{packageVersionId:$id}) {
      success
    }
  }
`, {
  id,
  headers: {
    accept: `application/vnd.github.package-deletes-preview+json`
  }
})

See @octokit/graphql for further details. You may also like the Explorer. The query result displayed there is exactly what you'll get from octokit.graphql().

octokit[scope][method]()

Query the GitHub REST API through a programmatic API. See docs for a complete list of methods.

octokit.request(route, options)

Query the GitHub REST API through a low-level method. Returns a promise for the response. See @octokit/request for details. You may prefer the programmatic API above.

Usage In Actions

Add an input to your action.yml:

inputs:
  token:
    default: ${{ github.token }}

const simpleOctokit = require('simple-octokit')
const octokit = simpleOctokit(process.env.INPUT_TOKEN)

Or require consumers of your action to (more explicitly) set the token in their env:

- uses: example-action
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

const simpleOctokit = require('simple-octokit')
const octokit = simpleOctokit()

Install

With npm do:

npm install simple-octokit

License

MIT © Vincent Weevers