Open Source Tools: Build – GitHub

On the last two posts of this series (JitPack, Travis & AppVeyor) I mentioned in passing another online service that is very popular and widely used: GitHub. The fact that I failed to mention this service before the introduction of the previous two goes to show how prevalent it is; you simply take it for granted because it’s there! There are of course other code hosting solutions in the wild, I started 11 years ago with SourceForge (with CSV no less, oh my!), such as BitBucket and GitLab however most of the online services we’ll continue to see on this series integrate seamlessly with GitHub. Some of this services may integrate with the other code hosting services.

In short, GitHub is a content hosting solution where most of the content is composed of code. I said mostly because some people have realized that the social aspects of the platform combined with collaborative workflows allow them to write documents in a similar fashion as we developers write code. GitHub has grown to be the place to host code, specially if you use Git as source control system; some refer to GitHub as Git’s killer app, in other words, the reason why many have switched from their previous SCM to Git.

On the surface Git is quite simple to use. Create an account, create a repository, push code, done. It’s UI has a minimalist design, basically what you see is what you get. It’s issue tracker is good enough although many have pointed out that it’s too simple, often referring to competing products as better in terms of being able to handle custom fields, workflows, hooks, notifications, and more. At first I agreed with this idea but after using GitHub’s issue tracker for quite some time (i.e, years) alongside the other options I like GitHub better as there’s no clutter, no distractions. YMMV.

One interesting feature of GitHub is it’s ability to use either Markdown or Asciidoc as its documentation formats, which make it very easy to write README files for example, or BUILD and INSTALL instructions, or a whole lot of documentation in the Wiki space reserved for a project. Another great feature is the definition of a custom branch named gh-pages. Any content pushed to that branch is automatically available on the web as static content; think of this as a quick hosting solution for more elaborate documentation, a manual, guide, or anything else your project may need. Here’s a concrete example, one of the projects I’ve manage is called Ikonli (icon packs for Java applications); the gh-pages branch hosts the user guide for this project. GitHub follows a naming convention to determine the URL used for the static content. Given the location of a repository of the form username/project then the website will be available at username.github.io/project, that is https://github.com/aalmiray/ikonli becomes http://aalmiray.github.io/ikonli. You can even automate generating the content and pushing it to the gh-pages branch, if you happen to use Gradle this task is dead simple

plugins {
    id 'org.ajoberstar.github-pages' version '1.7.1'
    id 'org.asciidoctor.convert'     version '1.5.3'
}

if (!project.hasProperty('githubUsername')) ext.githubUsername = ''
if (!project.hasProperty('githubPassword')) ext.githubPassword = ''

githubPages {
    repoUri = "https://github.com/${username}/${project.name}.git"
    pages {
        from asciidoctor.outputs.files
    }

    credentials {
        username = githubUsername
        password = githubPassword
    }
}

publishGhPages.dependsOn(asciidoctor)

Anytime you want to build the documentation (written in Asciidoc) and push the results to GitHub you only need to invoke

$./gradlew publishGhPages

There are of course more things that you can do with GitHub but the important thing to remember is the vast ecosystem of applications and services that surround it, enabling you to customize your codebase, engage with the community, generate reports, and other interesting stuff. You can also use GitHub as an OAuth provider, no need to create additional accounts on other services.

Disclaimer: I’m in no way related to GitHub nor the company behind it. I merely provide information on this service based on its free version.

Leave a Reply

Your email address will not be published. Required fields are marked *

ˆ Back To Top