Building Tools with GitHub: Customize Your Workflow

by Chris Dawson, Ben Straub

Overview

For your next project on GitHub, take advantage of the service’s powerful API to meet your unique development requirements. This practical guide shows you how to build your own software tools for customizing the GitHub workflow. Each hands-on chapter is a compelling story that walks you through the tradeoffs and considerations for building applications on top of various GitHub technologies.

If you’re an experienced programmer familiar with GitHub, you’ll learn how to build tools with the GitHub API and related open source technologies such as Jekyll (site builder), Hubot (NodeJS chat robot), and Gollum (wiki).

• Build a simple Ruby server with Gist API command-line tools and Ruby’s "Octokit" API client
• Use the Gollum command-line tool to build an image management application
• Build a GUI tool to search GitHub with Python
• Document interactions between third-party tools and your code
• Use Jekyll to create a fully-featured blog from material in your GitHub repository
• Create an Android mobile application that reads and writes information into a Jekyll repository
• Host an entire single-page JavaScript application on GitHub
• Use Hubot to automate pull request reviews

Product Details

ISBN-13:	9781491933503
Publisher:	O'Reilly Media, Incorporated
Publication date:	02/26/2016
Pages:	299
Product dimensions:	7.00(w) x 9.30(h) x 0.90(d)

About the Author

Chris Dawson comes from a family of public school teachers. From an early age, computers provided an always fascinating and often frustrating complement to learning and teaching for Chris. Notably inconspicuous at several notable startups and technology companies like Apple, Virage and RealNetworks, Chris gratefully had the opportunity to live on three continents and experience the power and dynamism of diverse communities. As such, it is with great relish that Chris has been participating in and documenting one of the most exciting learning communities of the 21st century: GitHub.

Ben Straub is a lifelong developer, and enthusiast of the craft of making great software. He's written software for over 15 years, has authored several books, and has recorded educational software training videos. He enjoys reading, taking his kids on bike rides, chocolate, dogs, those little notebooks you carry around with you, photography, a good weekend hack, traveling, writing, food, craftsmanship, a great pen, Markdown, music, movies, and talking to amazing people.

Table of Contents

Preface ix

1 The Unclad GitHub API 1

cURL 1

Breadcrumbs to Successive API Paths 2

The JavaScript Object Notation (JSON) Format 3

Parsing JSON from the Command Line 3

Debugging Switches for cURL 5

Important Headers 7

Following a Hypermedia API 7

Authentication 8

Usernarne and Password Authentication 8

OAuth 9

Status Codes 11

Success (200 or 201) 12

Naughty JSON (400) 12

Improper JSON (422) 13

Successful Creation (201) 13

Nothing Has Changed (304) 14

GitHub API Rate Limits 14

Reading Your Rate Limits 15

Conditional Requests to Avoid Rate Limitations 16

Accessing Content from the Web 17

JSON-P 18

CORS Support 19

Specifying Response Content Format 20

Summary 21

2 Gists and the Gist API 23

Easy Code Sharing 23

Gists Are Repositories 24

Embedding Gists Inside HTML 25

Embedding Inside Jekyll Blogs 25

Gist from the Command Line 25

Gists as Fully Functioning Apps 26

Gists that Render Gists 28

Going Deeper into the Gist API 29

Using Hypermedia Data from Octokit 30

Summary 32

3 GitHub Wikis with Gollum 33

"The Story of Smeagol…" 33

Repository Linked Wikis 34

Markup and Structure 35

Hacking Gollum 38

The Starting Point of a Gollum Editor 39

Programmaticalty Handling Images 40

Using the Rugged Library 42

Optimizing for Image Storage 45

Reviewing on GitHub 47

Improving Revision Navigation 50

Fixing Linking Between Comp Pages 51

Summary 52

4 Python and the Search API 53

Search API General Principles 53

Authentication 54

Result Format 54

Search Operators and Qualifiers 55

Sorting 56

Search APIs in Detail 57

Repository Search 57

Code Search 58

Issue Search 59

User Search 60

Our Example Application 61

User Flow 63

Python 64

AGitHub 65

WxPython 65

Pylnstaller 65

The Code 66

Git Credential Helper 67

Windowing and Interface 68

GitHub Login 72

GitHub Search 75

Displaying Results 77

Packaging 79

Summary 79

5 NET and the Commit Status API 81

The API 82

Raw Statuses 83

Combined Status 84

Creating a Status 85

Let's Write an App 85

Libraries 86

Development Environment 86

Sending the Request 89

OAuth Flow 91

Status Handler 96

Summary 97

6 Ruby and Jekyll 99

Learning and Building with Jekyll 99

What Is Jekyll? 99

Operating Jekyll Locally 100

Jekyll Blog Quick Start 101

YFM: YAML Front Matter 104

Jekyll Markup 106

Using the Jekyll Command 106

Privacy Levels with Jekyll 107

Themes 107

Publishing on GitHub 107

Hosting On Your Own Domain 108

Importing from Other Blogs 110

From Wordpress 110

Exporting from Wordpress Alternatives 112

Scraping Sites into Jekyll 112

Jekyll Scraping Tactics 113

Setting Up 114

Scraping Titles 116

Refinining with Interactive Ruby 117

Writing Tests and Caching 119

Writing Jekyll Posts 123

Using the Jekyll Command-Line Tool 126

Master Index File with Liquid Markup 128

Scraping Body and Author 130

Adding Images to Jekyll 131

Customizing Styling (CSS) 132

Inviting Contributions with GitHub "Fork" 134

Publishing Our Blog to GitHub 135

Summary 135

7 Android and the Git Data API 137

Setting Up 137

Creating a Jekyll Blog 137

Android Development Tools 138

Creating a New Project 139

Editing the Gradle Build File 141

Default Android Main 143

Android Automated Testing 147

Unit Tests for Our GitHub Client 147

Android UI Tests 151

Application Implementation 153

Code to Log In to GitHub 156

Code to Talk to GitHub 161

Writing the Blog Content 163

GitHub Services 164

The Base SHA from the Repository and Branch 165

Creating the Blob 166

Generating a Tree 166

Creating the Commit 167

Updating the Master Resource 169

Passing All Our Tests 169

Summary 171

8 CoffeeScript, Hubot, and the Activity API 173

The Activity API 173

Planning for PR Satisfaction Guaranteed 174

Considerations and Limitations 174

Creating a Vanilla Hubot 175

Creating a Slack Account 175

Running Hubot Locally 178

Installation on Heroku 180

Setting Up Heroku 180

Activity API Overview 181

Writing a Hubot Extension 182

Code Reviews via Pull Requests 183

Using the OAuth Token to Register for Events 189

Triggering Real Pull Requests 191

Handling PR Notifications as Post Requests over HTTP 194

Summary 217

9 JavaScript and the Git Data API 219

Building a Coffee Shop Database on GitHub 220

Set Up 220

Mapping Hostnames 221

Adding the Support Libraries 221

An AngularJS Application Using GitHub.js 222

Visualize Application Data Structure 225

Making Our App Testable 226

Test Data 231

CoffeeTech.js 231

Geocoding Support 233

City Data 236

Adding Login 236

Errors Already? 237

Displaying (Soon-to-Be) User-Reported Data 238

User-Contributed Data 240

Accepting Pull Requests 248

Toward a Safe Login Implementation 250

Authentication Requires a Server 250

Fixing Authentication with Firebase 251

Testing Firebase 253

Implementing Firebase Login 255

Summary 257

A GitHub Enterprise 259

B Ruby, NodeJS, (and the Shell) at GitHub 265

Index 271