This article is about hacking Github’s in-page source editor. If you’re a committer to a project, you can edit pages in-situ, with an editor they’ve embedded from Cloud9’s IDE project - Ace. Github is such a solid platform, I want to have custom editors for JSON documents that I’m using for configuration elsewhere. This makes the editing cycle more robust, and means you wouldn’t need developers to make changes to certain resources.

Clearly, I can’t wait for the Github people to add this feature :)

Chrome extension to the rescue

I found a project, Binged, that embeds an Angular app into the Google Search page. It doesn’t really work any more, but that’s not important. What is that it serves a minimalist demo of how to get this sort of thing working. Binged was written by Christian Pelczarski, and was a perfect start for what I wanted to do.

My test-case is a silly app that I use to demonstrate how minimalist Angular can be - a “whack a mole” game itself served up on Github-Pages. You can click on that link, and quickly play with the app (click moles or wholes) before coming back to continue reading this article.

My modification to the GH editor page, initially manifests itself as a button:

If you click it, the custom editor appears, and the Ace editor is hidden (via angular show/hide directives):

If you make a change, the commit button is enabled:

Pressing commit, writes the change to HEAD revision of the resource, as before. People who’ve used this facility won’t be surprised that you can immediately see it in the history for the file:

A less silly example

Of course, clicking moles or holes is silly, even if it does mutate a JSON state model that’s held on Github. Some people can’t expand that to a real feature-toggles example, though. Here’s a better case that is clipped from Logan McGrath’s blog entry on app-config-app (see below):

Imagine that inserted in the page, instead of the green Mole/Holes app.

Playing with it yourself

Here’s the project (a fork of Binged). To play with it, check it out, do a bower install, then in Chrome’s extensions capability, configure it as a manual extension:

Then fork my whack_a_mole_angular application so you can go and edit the JSON resource (as above).

Here’s the diff from Christian’s Binged to my MoleEditor.

What next

I’d love the Github people to formalize this sort of thing, allowing me to designate a repo (say for all in that org it to use. That would be a solution that doesn’t need a browser extension at all. The repo would have similar regex matchers to the chrome extension, and a formalized API for thunking into the editor page.

Failing that, I like a the GH user community to group together and have a system where a single Chrome extension could be configured to similarly obey some injectable editors for organization and/or per user, without those editors having to be bundled into the extension. If you’re interested and JavaScript skilled, reach out and we can collaborate on this.

Why do this?

I’m trying to re-do a piece that Logan McGrath and I did some years ago, for a larger “configuration as code” agenda. One that features Consul and git2consul too. There’s a flaw with my former Git & Sinatra approach in that you need to do a Git clone to make working copy so that you can serve up individual resources over HTTP. Immediately after that you’re going to realize the imperfection from the commit/pull/push cycle you need to do to keep the canonical master up to date. In other words Git is not design for client-server serving of individual resources in an editing cycle. The Github people have done exactly that though, and thunking into the GH app is very alluring.

My tool-chain in this blog entry is

Github + custom editor, and commits that causing gh-pages to re-deploy the standalone whack-a-mole app

For this to be a usable demonstration, I would change it to:

Github + custom editor, Github web-hooks to take up git2consul, Consult to broadcast to multiple config subscribers in its own high-availability way.

This solution is also limited to just JSON documents. Unless there’s some Angular (or equiv) magic to edit YAML, XML and properties or ini files, all your config will need to be JSON. That’s not the worst news ever. Those other types are popular configuration choices, of course.

Ryan Breen has pioneered some of this, and I want master the technologies he’s put together for my bigger “Configuration as Code” agenda, by adding in the editor piece, as I had it in the app-config-app experiment.


June 7th, 2015