octokit is here

Since I started working on the JavaScript SDKs we worked towards an all-batteries-included octokit package, and now it's here: octokit.

It covers

• REST API requests
• GraphQL requests
• OAuth Apps
• GitHub Apps
• Webhooks
• Actions (WIP)

As well as the wiring up between these components. For example, when importing the App SDK from the octokit package, a pre-authenticated octokit instance will be passed to webhook event handlers:

const app = new App({
  appId,
  privateKey,
  webhooks: { secret },
});

app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  return octokit.rest.issues.createComment({
    owner: payload.repository.owner.login,
    repo: payload.repository.name,
    body: "Hello, World!",
  });
});

The octokit package also implements best practices for paginating REST API requests, request throttling, and request retries.

It's a great starting point if you want to create any kind of script, app, or integration that works with any of GitHub's platform APIs.

At the same time it's fully decomposable. If bundle size or memory usage becomes a problem, you can always built your own Octokit with only the code you need, down to stateless functions such as @octokit/endpoint, @octokit/request, @octokit/graphql, @octokit/oauth-methods, or @octokit/webhooks-methods.

Jason Lengstorf invited me to do an introduction to Octokit as part of his "Learn with Jason" show: check out GitHub Automation with Octokit. Unfortunately GitHub Actions have been down when we recorded the show, I was able to do a follow up during GitHub's "30 minutes to merge" show: Automating nose booping using GitHub Actions.

Enjoy!

🆕 New projects

• octokit/authentication-strategies.js

  • The authentication-strategies repository is only a README to list existing official and community-contributed authentication strategies as well as documenting how to create your own.
  • This new repository replaces the now deprecated @octokit/auth package

• @octokit/auth-oauth-device

  @octokit/auth-oauth-device is an authentication strategy for GitHub's new OAuth Device flow.

• @octokit/auth-oauth-user

  @octokit/auth-oauth-user is an authentication strategy to create OAuth user tokens.

• @octokit/oauth-methods

  Static functions for all things OAuth.

• @octokit/webhooks-methods

  Static functions for all things webhooks.

• octokit/handbook

  A handbook for everyone who maintains any kind of library for GitHub's platform APIs. We keep track of all our gotchas in there as we build the JavaScript Octokit to save you a lot of head aches down the road.

📰 Other news

• @octokit/rest

  We no longer recommend to use @ocotkit/rest, use octokit instead. We will continue to maintain the package for the foreseeable time due to its wide usage as it was the first Octokit package we created. But for new projects we strongly recommend to use octokit now.

• @octokit/webhooks

  The @octokit/webhooks package as well as the examples, schemas, and type definitions from https://github.com/octokit/webhooks are mostly maintained by @octokit/js-community. In particular by @wolfy1339 in the past 3 months. Thank you for all the outstanding work!

  • We released @ocotkit/webhooks v9 in April with several smaller breaking changes to make the package more coherent with the other @octokit packages, and to default to the sha256 algorithm for webhook request verifications.
  • The types for @octokit/webhooks have been greatly improved. The https://github.com/octokit/webhooks repository now has a nearly complete list of all event/action combination for payload examples, schemas, and types. It's much more complete that what you can find in GitHub's own webhooks reference documentation, and we hope to make it part of GitHub's official OpenAPI spec in future.
  • There are now 3 different packages so you only get what you need:
    1. @octokit/webhooks-examples
    2. @octokit/webhooks-schemas
    3. @octokit/webhooks-types

• probot

  • We released Probot v12. It upgrades to the latest @octokit/webhooks and its greatly improved type definitions for all webhook events.
  • Support for the * event has been removed, use app.webhooks.onAny() instead
  • app.webhooks.middleware is no longer set, and the webhookPath option for the Probot constructor has been removed. Both are covered by createNodeMiddleware.

• @octokit/core

  • error.response is now set on all request errors. That deprecates error.headers, which can now be accessed at error.response.headers.
  • Types no longer breaks when using Octokit.plugin() with a plugin function that returns void instead of an API extension object.

• @octokit/app

  • similar to @octokit/webhooks there were several breaking changes to improve coherence with other @octokit packages and to use the sha256 algorithm to verify webhook requests (summary of changes)
  • Several OAuth APIs have been added to refresh an expiring user-to-server token, to scope an existing user-to-server token, and to add support for the device OAuth flow.

• @octokit/oauth-app

  • All stateless OAuth methods have been moved to its dedicated package: @octokit/oauth-methods.
  • When using with GitHub Apps credentials, you must set clientType to "github-app" now in order to take full advantage of types that implement the nuanced differences in OAuth features between OAuth Apps and GitHub Apps.

• @octokit/auth-oauth-app

  • Starting with version 4, @octokit/auth-oauth-app is now only supporting authenticating as the OAuth App. For user authentication, use @octokit/auth-oauth-user

  • The types have been improved to accommodate the differences of OAuth Apps and GitHub Apps' OAuth features. The two are differentiated by passing a new type key to the strategy function, which can be set to "auth-app" (default) or "github-app".

  • The auth() function now supports a factory option, which can be set to createOAuthUserAuth.

    const {
      createOAuthAppAuth,
      createOAuthUserAuth,
    } = require("@octokit/auth-oauth-app");
    
    const appAuth = createOAuthAppAuth({
      clientType: "github-app",
      clientId: "lv1.1234567890abcdef",
      clientSecret: "1234567890abcdef1234567890abcdef12345678",
    });
    
    const userAuth = await appAuth({
      type: "oauth-user",
      code,
      factory: createOAuthUserAuth,
    });
    
    // will create token upon first call, then cache authentication for successive calls,
    // until token needs to be refreshed (if enabled for the GitHub App)
    const authentication = await userAuth();

    That can be used to e.g. return a pre-authenticated octokit instance, as it's done internally by app.getUserOctokit()

• @octokit/auth-app

  • Similar to the changes for @octokit/auth-oauth-app, auth({ type: "oauth-user" }) now supports a factory function.
  • Support for OAuth device flow has been added

• @octokit/request-error

  • Every @octokit/request-error instance now includes a error.response key with the full response object. This deprecates error.headers.

• @octokit/create-octokit-project

  You can now us npm init Octokit-project to create a new Octokit plugin or a new Octokit authentication strategy package.

• @octokit/plugin-rest-endpoint-methods

  Endpoint methods are no longer set on octokit.* directly, instead they are set on octokit.rest.*. That will free up the top level octokit.* scope for higher-level plugins.

In yet other news, I started a helpdesk with live coding shows on Twitch. If you have any questions about Octokit, GitHub Platform APIs and/or automation, please let me know!

GitHub Platform Changes

• All new GitHub projects (beta) and Issue Forms (beta) - unfortunately no APIs for either yet.
• Discussions now support labels
• GitHub Actions: Maintainers must approve first time contributor workflow runs
• Authenticating with a query parameter will be removed on September 8
• GitHub Actions: Limit workflow run or job concurrency
• Releases can now be linked to a discussion and have reactions
• Compare REST API now supports pagination
• New formats for authentication tokens
• Discussions APIs
• Environments secrets, Environments protection, deployment reviewers
• GraphQL: summary. Most notably, you can use GraphQL to interact with discussions and sponsors.
• The REST API now returns deprecation and sunset headers for deprecated APIs. Octokit is logging deprecation warnings if the response headers are present.
• REST API Endpoints
  • GET /repos/{owner}/{repo}/actions/runs/{run_id}/approvals
  • {GET,POST} /repos/{owner}/{repo}/actions/runs/{run_id}/pending_deployments
  • GET /repos/{owner}/{repo}/environments
  • {GET,PUT,DELETE} /repos/{owner}/{repo}/environments/{environment_name}
  • GET /repositories/{repository_id}/environments/{environment_name}/secrets
  • GET /repositories/{repository_id}/environments/{environment_name}/secrets/public-key
  • {GET,PUT,DELETE} /repositories/{repository_id}/environments/{environment_name}/secrets/{secret_name}
  • GET /repos/{owner}/{repo}/pages/health
  • POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve
  • POST /repos/{owner}/{repo}/releases/{release_id}/reactions
  • POST /repos/{owner}/{repo}/content_references/{content_reference_id}/attachments
  • GET /repos/{owner}/{repo}/compare/{basehead}
• Webhooks
  • discussion
  • discussion_comment
• App permissions
  • POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve requires actions write
  • PATCH /user requires profile write
  • GET /repos/{owner}/{repo}/events/issues requires meta read
  • GET /user/interaction-limits requires interaction_limits read
  • {PUT,DELETED} /user/interaction-limits requires interaction_limits write
  • GET /users/{username}/events/orgs/{org} requires organization_events read

Next

Priorities might change, but here is a list bigger projects that we started to work on or plan to soon.

1. Probot

Probot currently has a lot of logic that also exist in @octokit/app. To remove the code duplication, we will migrate probot to use @octokit/app internally. We created @octokit/app in parallel with Probot v11, they should be fairly compatible already. A benefit of the change will be that we get OAuth APIs for free, which are currently not supported in Probot, but have been requested for a long time.

2. ES Modules

Now that all currently supported Node versions have native support for ES Modules, many package authors started the transition from Node's own module system (CommonJS) to the ES module system which has been created for the web and standardized by the W3C.

Given that Octokit is a set of SDKs and libraries meant for all environments that run JavaScript, the transition to native ES Modules will greatly decrease the maintenance overhead and will decrease - ideally altogether remove - the need for any build tools.

The current plan is to continue support for the latest versions of packages released as CommonJS for some time. We will not attempt to publish our packages with dual support (CommonJS + ES Modules).

3. Separation of Code and Types

Currently all JS Octokit modules are written in TypeScript and compiled to JavaScript + TypeScript Declaration Files.

We plan to rewrite the TypeScript source files into native JavaScript and add the .d.ts declaration files into the source code. Besides testing the code, add tests for types.

Together with the migration to ES Modules, this should remove any need for build tools.

4. Composable Types

Currently all JS Octokit modules depend on @ocotkit/types. @octokit/types include definitions for all 600+ REST API endpoints and primitives such as types for Requests and responses that are not extendable.

Once we separate code and types, we can take advantage of declaration merging and global augmentation to make it possible for imported code to amend the global Octokit Types.

This will make it possible for plugin developers to extend Octokit constructor option types, response types, and more.

Most importantly it will enable as to make developing against GitHub Enterprise Server and AE a better experience, as the types for these targets will be loaded explicitly, and will not conflict with types for api.github.com.

Contributions welcome

If you'd like to contribute to @octokit, here are some interesting self-contained projects you might be interested in:

• Webhooks Example Payloads. The webhooks schemas and types are already fantastic but not yet entirely complete. They all depend on example payloads, some of which are still missing. You can help us complete the list at octokit/webhooks#301

• GraphQL Pagination. A repository for @octokit/plugin-paginate-graphql exists already, we "just" need to implement it: octokit/plugin-paginate-graphql.js#1 The idea is to utilize GraphQL variable naming conventions, see the discussion in the pull request and the linked issues.

  I'd estimate this to be 1-2 days of work, more if you are unfamiliar with Octokit.

  octokit/plugin-paginate-graphql.js#1

• Extract events logic from @octokit/webhooks into @octokit/events. Not all GitHub Events are sent via webhooks. Some are only available to GitHub Actions, such as the schedule event.

  I would like to move all event-related logic into a new @octokit/events package. @octokit/webhooks should only care about webhooks-specific logic, such as payload verification and the http request lifecycle

  octokit/webhooks.js#474

For smaller tasks, see open @octokit issues with the help-wanted label

💝 Thanks

I appreciate the continuous support of the @octokit/js-community team. In particular @wolfy1339 who took ownership of most things webhooks, and @oscard0m who continuous to be a big help across the @octokit repositories. Both are recurring contributors to Probot and other adjacent projects.

• Thanks to @wolfy1339 for migrating the first Octokit module to ES Modules: octokit/fixtures#407, octokit/fixtures#411
• Thanks to @honnix for making the middleware exported by @octokit/webhooks compatible with express! octokit/webhooks.js#534
• Thanks to @jablko for helping resolve a TypeScript compile error in octokit/webhooks.js#461 and for improving the README in octokit/webhooks.js#453
• Thanks to @gimenete for waiting 2+ years until we finally were able make webhooks verification more reliably by using the raw request body instead of using a JSON object octokit/webhooks.js#76
• Thanks to @pholleran for providing webhooks payload examples for code_scanning events in octokit/webhooks#371
• Thanks to @Eddman for adding GitHub Enterprise Server 3.0 support in octokit/plugin-enterprise-server.js#363
• Thanks to @NickLiffen we now have a repositoryNames option in @octokit/auth-app: octokit/auth-app.js#279. Nick also clarified the repositoryIds option via octokit/auth-app.js#278
• Thanks to @Andarist help in gr2m/javascript-plugin-architecture-with-typescript-definitions#31 we were able to improve the Octokit constructor option types in octokit/core.js#312
• Thanks to @MunifTanjim work in gr2m/before-after-hook#81 we were able to add proper types to the octokit.hook.* APIs in octokit/core.js#301
• Many thanks to @ptomulik for all their help with @octokit/plugin-paginate-rest! octokit/plugin-paginate-rest.js#307, octokit/plugin-paginate-rest.js#305, octokit/plugin-paginate-rest.js#291, octokit/plugin-paginate-rest.js#284, octokit/plugin-paginate-rest.js#283, octokit/plugin-paginate-rest.js#282
• Thanks to @eamodio for reporting a problem that lead to some response types being never in octokit/types.ts#271 and for fixing it in octokit/types.ts#272
• Thanks to @laughedelic for making @octokit/oauth-app compatible with Deno usage in octokit/oauth-app.js#221
• Thanks to @lumaxis for making logging the correct error URL via octokit/oauth-methods.js#17
• Thanks to @wperron for all their help with making Octokit fully compatible with Deno #2079, #2075 (comment)

Thanks to these documentation improvements

• Many thanks to @jeffmcaffer for greatly improving the README of the new octokit package in #2080
• Thanks to @imwiss for many improvements to the Octokit handbook via octokit/handbook#1
• Thanks to @unalterable for fixing README links in #2105
• Thanks to @C0ZEN for fixing the linting setup and improving the README in #2101
• Thanks to @mktcode for updating the table of contents in #2099
• Thanks to @Martii for fixing the link to the new discussions forum in #2090
• Thanks @tetov for fixing a typo in #2089
• Thanks to @UziTech for fixing README links in #2057
• Thanks to @sidrao2006 for fixing README links in #2055
• Thanks to SvanBoxel for adapting GitHub's new name for GitHub Business Cloud in octokit/plugin-enterprise-cloud.js#309
• Thanks to @samrose3 for fixing the usage example in octokit/authentication-strategies.js#159
• Thanks to @AGarcia-Clarity for fixing a README typo in octokit/auth-oauth-app.js#158
• Thanks to @joscha for fixing the usage example in octokit/core.js#358
• Thanks to @iMichka for fixing the usage example in octokit/action.js#286
• Thanks to @eskersoftware for resolving a usage example in octokit/oauth-app.js#226
• Thanks to @hopkinsth for fixing the plugins documentation in octokit/rest.js#63

Thanks to these great bug reports

• Thanks to @Tohaker for making us aware that using a url variable with @octokit/graphql resulting in an error octokit/graphql.js#264
• Thanks to @florian30491 for their detailed report about type problems with the octokit.rest.pulls.requestReviewers() method POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers in octokit/types.ts#319
• Thanks to @tlbdk for their detailed bug reports in octokit/types.ts#283 and octokit/types.ts#274
• Thanks to @stathismor for making us aware that the "Ask a question" link was not working via octokit/rest.js#49
• Thanks to @bcoe for reporting a typescript compilation error with @octokit/rest and to @bcoe and @el7cosmos for helping us working through it octokit/rest.js#45
• Thanks to @AjkayAlan for their bug report at octokit/request.js#403 and for moving it to github/rest-api-description#419 once we identified the cause of it

Just a quick update: GitHub decided not to extend the contract for my work on @octokit. I was only told a week ago. The JavaScript Octokit has no active maintainer as of this week.

I was hoping to finish the work on @octokit-next/core but the remaining time did not suffice. There are a few more things remaining to complete the first milestone.

I've disabled all automated pull requests for dependency and OpenAPI updates to reduce the noise. I unwatched all the repositories. I'm sorry for the inconvenience but there is nothing I can do about it 😞

I'll post an update if anything changes.

Hi everyone! 👋

I am excited to announce that GitHub is building a dedicated SDK team that will actively maintain all Octokit libraries (JS, Ruby, and .NET). The team’s mission will be to maintain, improve, and create Octokit libraries that will delight developers and improve GitHub’s ecosystem.

Our first role on the SDK team is now open and available here. If you’re interested, I’d love to chat with you!