Octokit – Your official GitHub Platform Toolkit

An insight into our work on Octokit.js and tooling we built along the way to carve the way for other languages

Transcript

1. OMG HAPPY BIRTHDAY GITHUB TURNED 10, I mean I would sing all you hubbers happy birthday especially with this great audio setup we got here but I better spare you my singing voice :D I just want to say congratulations to all the hubbers here tonight, we see and love all the hard work you are doing, we celebrate the ups and suffer with you trough the downs. Here is to the next 10 years! Congratulations! HAPPY BIRTHDAY! github.com/ten @gr2m | GitHub Constellation LA 2018
2. Octokit is all about making the life easier for developers to integrate with and build upon the GitHub platform. Octokit Your official™ GitHub Platform Toolkit @gr2m | GitHub Constellation LA 2018
3. For libraries, there are currently three: one for Ruby, which is maintained by GitHubbers. .net which is maintained by a community maintainer: Ryan Gribble and now JavaScript. Platform toolkit as in Libraries @gr2m | GitHub Constellation LA 2018
4. Octokit Rest is an API wrapper client and just like the other languages we try to make it reflect the idioms and conventions of its community. In the case of JavaScript it means that it must run in both Node.js and the browser, itʼs modular and we are watching its bundle size as part of the CI octokit/rest.js // Browser: <script scr="octokit-rest.min.js"></script> // Node: const Octokit = require('@octokit/rest') const octokit = new Octokit() const repos = await octokit.repos.getForOrg({ org: 'octokit', type: 'public' }) @gr2m | GitHub Constellation LA 2018
5. Here is another part of the JavaScript octokit, which is to handle webhooks. You can load the event handler API client to use it with your server framework of preference or load it as middleware that you can pass into the native http server. octokit/webhooks.js const Webhooks = require('@octokit/webhooks') const {createServer} = require('http') const webhooks = new Webhooks({ secret: 'mysecret' }) webhooks.on('issues', ({id, name, payload}) => { if (payload.action === 'created') { console.log(`New issue ${payload.issue.title}`) } }) createServer(webhooks.middleware).listen(3000) @gr2m | GitHub Constellation LA 2018
6. REST · Webhooks OAuth · GraphQL GitHub Apps @gr2m | GitHub Constellation LA 2018
7. Besides the REST API wrapper, the webhooks handler we are also working on tools for OAuth (both client and server), a GraphQL client and a low-level that helps with GitHub Apps. To build actual GitHub apps you can use Probot, which is not part of Octokit but is using it internally. Probot is an independent Open Source project, initiated as a side project by Brandon Keepers. Here you can see the source code for the work in progress app. In less than 20 lines of code, it checks if a pull request has "WIP" in its title and sets the pull request status accordingly. Itʼs also a great segue because JavaScript Octokit is very much work Probot module.exports = (robot)= > { robot.on([ 'pull_request.opened', 'pull_request.edited' ], ({github, payload, repo}) => { const {title, head} = payload.pull_request const isWip = /\bwip\b/i.test(title) github.repos.createStatus(repo({ sha: head.sha, state: isWip ? 'pending' : 'success', description: isWip ? 'work in progress – do not merge!' : 'ready for review', context: 'WIP' })) }) } @gr2m | GitHub Constellation LA 2018
8. Hi! I am Gregor Martynus. Iʼm working with JavaScript for nearly two decades now. Iʼm maintaining or contributing to some JavaScript and Node.js ecosystem projects, for http mocking, automated releases, Greenkeeper (which is automated dependency updates) and Probot, the GitHub App framework that I used to build the work in progress app shown before. Probot is an independent Open Source project, started by GitHubbers, but with many outside contributors. It's hands down the best way to build GitHub apps today and Zeke will show you some more of it today And what is special is that I am not a GitHub employee, but hired as an outside contractor. Gregor Martynus » Maintainer of Octokit.js » JS ecosystem tooling Maintainer/Contributor: » nock (Mocking) » semantic-release » Greenkeeper (Updates) » Probot (GitHub App Framework) » Not a GitHub employee @gr2m | GitHub Constellation LA 2018
9. Who of you worked with GitHubʼs REST API, GraphQL, Webhooks? I feel your pain. Because just as you, I can only use what is publicly accessible. And everything I do is publicly accessible, not only the result, but everything, the entire process. It also means that you can contribute to accelerate the bits that you care about. I personally care a lot about inclusive, welcoming Open Source communities and working on Octokit gives me not only the opportunity to work on very interesting technology but also make it in a way that allows for outside participation. So if you never contributed to Open Source before or just enjoy working on other projects from time to time, hit me up, Iʼm happy to walk you trough. no shortcuts. open source. @gr2m | GitHub Constellation LA 2018
10. Maybe the biggest pain that I experienced when building Apps using the GitHub API, or any external service really, is to create integration tests. You cannot test against the real API so you rely on http mocks. And http mocks have the problem of getting out of date, and what happens then is all your tests pass but your app or service breaks when in production. Iʼm sure that GitHub has tons and tons of mocks in their internal tooling but as mentioned before, I donʼt have access to that. But building a REST API client, I rely heavily on mocks so I created my own Platform toolkit as in HTTP MOCKS @gr2m | GitHub Constellation LA 2018
11. Octokit Fixtures is now a seperate project that can be used across all the Octokits and Iʼd be very interested in making them work for your own projects, too. @gr2m | GitHub Constellation LA 2018
12. The coolest thing is that the mocks will never get out of date because we have a daily cron job that records new fixuters, normalizes them and compares them to the existing ones. If there are any changes we recive a pull request. And once merged a new version of the fixtures is released automatically using semantic-release. @gr2m | GitHub Constellation LA 2018
13. To make the Octokit fixtures language agnostic, I created a server which we also continously deploy, so you donʼt even need to setup anything and can test against it directly. @gr2m | GitHub Constellation LA 2018
14. If you want to run it yourself, you can install it with npm. If donʼt use Node.js, then you can download it as a single binary for Linux, Windows or Mac, too. With the auto-updating fixtures, we can guarantee that Octokit REST libraries are always working with the latest REST API. And as a nice side effect we caught a few accidental API changes by GitHub that have been resolved before most users realised. npm install @octokit/fixtures npm install @octokit/fixtures-server @gr2m | GitHub Constellation LA 2018
15. Another thing that we donʼt want to get out- of-date is documentation. GraphQL is less affected by this as the API documentation is part of the specification, but REST API client documentation are notorously affected by it, unless they are generated by the source code. We donʼt have the source code so we did something else Platform toolkit as in Documentation @gr2m | GitHub Constellation LA 2018
16. Octokit routes is not a library, but a machine-readable, always up-to-date specification of GitHubʼs REST API. And it is a script that runs on a daily cronjob, which scrapes the entire GitHub REST API documentation and transforms it into the a big JSON file. @gr2m | GitHub Constellation LA 2018
17. { "name": "Lock an issue", "enabledForApps": true, "method": "PUT", "path": "/repos/:owner/:repo/issues/:number/lock", "params": [ { "name": "lock_reason", "type": "string", "description": "The reason for locking...", "required": false } ], "description": "Users with push access can...", "documentationUrl": "https://developer.github.com/v3/issues/#lock-an-issue" } @gr2m | GitHub Constellation LA 2018
18. @gr2m | GitHub Constellation LA 2018
19. @gr2m | GitHub Constellation LA 2018
20. @gr2m | GitHub Constellation LA 2018
21. Platform toolkit as in Developer Experience @gr2m | GitHub Constellation LA 2018
22. Auto-complete, inline errors, for both REST APIs and GraphQL queries @gr2m | GitHub Constellation LA 2018
23. @gr2m | GitHub Constellation LA 2018
24. Platform toolkit as in Stich & Remix @gr2m | GitHub Constellation LA 2018
25. GraphQL Stitching const githubStitch = require('@gr2m/express-github-stitch') const schema = ` extend type User { twitter: String } ` const resolvers = mergeInfo => ({ User: { twitter: { fragment: `fragment UserFragment on User { websiteUrl, login }`, async resolve (parent, args, context, info) { const {body} = await got(`twitter.com/${parent.login}`) const $ = cheerio.load(body) const twitterUrl = $('.PHC-url [href]').attr('title') if (isSameUrl(twitterUrl, parent.websiteUrl)) { return parent.login } } } } }) const app = require('express')() app.use(githubStitch({schema, resolvers})) app.listen(3000) @gr2m | GitHub Constellation LA 2018
26. THANKS @gr2m | GitHub Constellation LA 2018