Building tools with GitHub : customize your workflow

For your next project on GitHub, take advantage of the service{u2019}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{u2019}re an experienced programmer familiar with GitHub, you{u2019}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{u2019}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 Cover 1 Copyright 4 Table of Contents 5 Preface 11 Why APIs and Why the GitHub API? 12 Structure of This Book 13 Who You Are 16 What You Will Learn 16 GitHub “First Class” Languages 17 Operating System Prerequisites 18 Who This Book Is Not For 18 Conventions Used in This Book 19 Using Code Examples 19 O’Reilly Safari 20 How to Contact Us 20 Acknowledgments 21 Chapter 1. The Unclad GitHub API 23 cURL 23 Breadcrumbs to Successive API Paths 24 The JavaScript Object Notation (JSON) Format 25 Parsing JSON from the Command Line 25 Debugging Switches for cURL 27 Important Headers 29 Following a Hypermedia API 29 Authentication 30 Username and Password Authentication 30 OAuth 31 Status Codes 33 Success (200 or 201) 34 Naughty JSON (400) 34 Improper JSON (422) 34 Successful Creation (201) 35 Nothing Has Changed (304) 36 GitHub API Rate Limits 36 Reading Your Rate Limits 37 Conditional Requests to Avoid Rate Limitations 37 Accessing Content from the Web 39 JSON-P 39 CORS Support 41 Specifying Response Content Format 42 Summary 43 Chapter 2. Gists and the Gist API 45 Easy Code Sharing 45 Gists Are Repositories 46 Embedding Gists Inside HTML 47 Embedding Inside Jekyll Blogs 47 Gist from the Command Line 47 Gists as Fully Functioning Apps 48 Gists that Render Gists 50 Going Deeper into the Gist API 51 Using Hypermedia Data from Octokit 52 Summary 54 Chapter 3. GitHub Wikis with Gollum 55 “The Story of Smeagol...” 55 Repository Linked Wikis 56 Markup and Structure 57 Hacking Gollum 60 The Starting Point of a Gollum Editor 61 Programmatically Handling Images 62 Using the Rugged Library 64 Adding Images to a Review File 67 Optimizing for Image Storage 67 Reviewing on GitHub 70 Improving Revision Navigation 72 Fixing Linking Between Comp Pages 73 Summary 74 Chapter 4. Python and the Search API 75 Search API General Principles 75 Authentication 76 Result Format 76 Search Operators and Qualifiers 77 Sorting 78 Search APIs in Detail 79 Repository Search 79 Code Search 80 Issue Search 81 User Search 82 Our Example Application 83 User Flow 85 Python 86 AGitHub 87 WxPython 87 PyInstaller 87 The Code 88 Git Credential Helper 89 Windowing and Interface 90 GitHub Login 94 GitHub Search 97 Displaying Results 99 Packaging 101 Summary 101 Chapter 5. .NET and the Commit Status API 103 The API 104 Raw Statuses 105 Combined Status 106 Creating a Status 107 Let’s Write an App 107 Libraries 108 Development Environment 108 Sending the Request 111 OAuth Flow 113 Status Handler 118 Summary 119 Chapter 6. Ruby and Jekyll 121 Learning and Building with Jekyll 121 What Is Jekyll? 121 Operating Jekyll Locally 122 Jekyll Blog Quick Start 123 YFM: YAML Front Matter 126 Jekyll Markup 128 Using the Jekyll Command 128 Privacy Levels with Jekyll 129 Themes 129 Publishing on GitHub 129 Hosting On Your Own Domain 130 Importing from Other Blogs 132 From Wordpress 132 Exporting from Wordpress Alternatives 134 Scraping Sites into Jekyll 134 Jekyll Scraping Tactics 135 Setting Up 136 Scraping Titles 138 Refinining with Interactive Ruby 139 Writing Tests and Caching 141 Writing Jekyll Posts 145 Using the Jekyll Command-Line Tool 148 Master Index File with Liquid Markup 150 Scraping Body and Author 152 Adding Images to Jekyll 153 Customizing Styling (CSS) 154 Inviting Contributions with GitHub “Fork” 156 Publishing Our Blog to GitHub 157 Summary 157 Chapter 7. Android and the Git Data API 159 Setting Up 159 Creating a Jekyll Blog 159 Android Development Tools 160 Creating a New Project 161 Editing the Gradle Build File 163 Default Android Main 165 Android Automated Testing 169 Unit Tests for Our GitHub Client 169 Android UI Tests 173 Application Implementation 175 Code to Log In to GitHub 178 Code to Talk to GitHub 183 Writing the Blog Content 185 GitHub Services 186 The Base SHA from the Repository and Branch 187 Creating the Blob 188 Generating a Tree 188 Creating the Commit 189 Updating the Master Resource 191 Passing All Our Tests 191 Summary 193 Chapter 8. CoffeeScript, Hubot, and the Activity API 195 The Activity API 195 Planning for PR Satisfaction Guaranteed 196 Considerations and Limitations 196 Creating a Vanilla Hubot 197 Creating a Slack Account 197 Running Hubot Locally 200 Installation on Heroku 202 Setting Up Heroku 202 Activity API Overview 203 Writing a Hubot Extension 204 Code Reviews via Pull Requests 205 Using the OAuth Token to Register for Events 211 Triggering Real Pull Requests 213 Handling PR Notifications as Post Requests over HTTP 216 Summary 239 Chapter 9. JavaScript and the Git Data API 241 Building a Coffee Shop Database on GitHub 242 Set Up 242 Mapping Hostnames 243 Adding the Support Libraries 243 An AngularJS Application Using GitHub.js 244 Visualize Application Data Structure 247 Making Our App Testable 248 Test Data 253 CoffeeTech.js 253 Geocoding Support 255 City Data 258 Adding Login 258 Errors Already? 259 Displaying (Soon-to-Be) User-Reported Data 260 User-Contributed Data 262 Accepting Pull Requests 270 Toward a Safe Login Implementation 272 Authentication Requires a Server 272 Fixing Authentication with Firebase 273 Testing Firebase 275 Implementing Firebase Login 277 Summary 279 Appendix A. GitHub Enterprise 281 Installation 281 Administration 282 Endpoints 282 Full Hostnames Versus Mount Points 282 Command-Line Client Tools: cURL 283 Example Request Using a Client Library 283 Ruby Client Configuration 283 Java 283 JavaScript 284 Python 284 C# 284 Management API 285 Documentation 285 Appendix B. Ruby, NodeJS, (and the Shell) at GitHub 287 GitHub and Ruby 287 Installing Ruby 288 Important Ruby and RVM Concepts 289 Potential Problems Installing Ruby 289 GitHub Is Excited about NodeJS 290 NodeJS Installation 290 Node Version Manager 290 package.json 291 Command-Line Basics and the Shell 291 Shell Comments 291 Providing Variables to Commands 291 Splitting Commands into Multiple Lines 292 Piping Output to Successive Commands 292 Redirection 292 Index 293 About the Authors 301