This WordPress plugin creates a custom GitHub dashboard for non-tech teams.
We recently faced a communication challenge encountered by most startups. Our sales team needed more visibility into the development process. They need to know when a particular feature was going to be added, or a bug fixed. We eventually solved this problem by building a simple, easy-to-deploy, open source tool.
The tool presents a secure way for users without GitHub accounts to search and view GitHub issues, and to easily track the release pipeline. We call it GitHub Pipeline.
Alternative options
Initially, we assumed there must be an existing tool for the job. But after a fair amount of searching and experimenting, we couldn't find anything matching our criteria. This is what we wanted:
An intuitive, customisable interface
Security and precise control over permissions and access
A quick and easy set-up
I'll go through a few of the tools we tried first and explain why they didn't match our needs. Perhaps they will meet yours.
Ad hoc
We had started with direct messages, but we rapidly outgrew those. Then we added a tracking spreadsheet, which quickly got stale. After that, we added a channel on Slack, but people were reluctant to ask questions. We realised we needed to give the sales team its own window into GitHub.
GitHub itself
First, we considered creating GitHub accounts for every sales team member, giving them direct access to the entire repository. That approach required the least effort.
However, we didn't want to simply dump the sales team into GitHub. Its issue tracking interface is familiar to devs, but overwhelming to normal humans, and not customisable. Also, the rules for interaction aren't obvious. There is no way to create a view to show only a specific set of issues relevant to a particular audience. In addition, it meant giving full access to the code repository to everyone – even remote salespeople.
We looked at giving Sales access to GitHub issues only, since this would keep the code secure. GitHub doesn't exactly support this. It does suggest setting up a shadow 'issue-only' repository, but this seemed like a hassle (especially the idea of using cross-repository links). Bottom line: GitHub permissions are basically an all-or-nothing choice between read-everything or write-everything. So you can't, say, allow a user to add labels to issues but not push code.
Project management tools
Task lists are another approach we tried. We were already using Asana, but found that integrating it with GitHub was rather cumbersome: it required us to manually add code snippets to every GitHub issue while creating corresponding Asana tasks.
Waffle.io was another promising option. The interface is clear and intuitive, and easy to set up – like a scrum board for project management. However, Waffle was not configurable enough. For example, it was difficult to display issues that had been closed in the past, which was unhelpful as our sales team needed to be able to check if a feature had been implemented already. Waffle also required that everyone authenticate through a GitHub account with full repository read permissions.
Introducing GitHub Pipeline
In the end we rolled up our sleeves and spent a few hours building our own tool: GitHub Pipeline. It is a simple, open source WordPress plugin that makes it easy to present issues and milestones from a GitHub project using shortcodes.
The WordPress shortcode API is extremely powerful. Shortcodes can be used across an entire website: static pages, blog posts … basically anywhere with content. For example, the following code is all you need to show all of your project's open issues that have the 'label' bug:
[gh_issues state="open" label="bug"]
You can allow users to search for issues as well, and searches can be restricted to issues with specific labels. This will display a search bar that will return any matching issues with the 'feature' label:
[gh_searchform label="feature"]
The ability to filter by labels and state (open or closed) gave us the flexibility to create customised views of exactly the information that we wanted, without any extra 'noise'.
One thing we discovered along the way is that GitHub conventions often need to be explained to the untrained. Because Pipeline is a GitHub plugin, it makes it much more simple to include annotations, instructions, and links to additional resources alongside GitHub data.
WordPress platform
We thought hard about the most efficient way to distribute Pipeline, and we chose to use WordPress as a platform because it's free and ubiquitous. It's also very flexible and easy to customise. If you already have a WordPress site, just install the plugin and you're ready to go straight away. If you don't have a WordPress site but have installed one before, you can have a Pipeline site set up in about 15 minutes.
GitHub Pipeline allows us to maintain tight control over who can access our GitHub repository because the tool interacts with the GitHub API using an OAuth token. This means your users don't need GitHub accounts, let alone write permissions.
Conclusion
I consider this project successful in a couple of different ways. First, it solved our problem. Sales feedback included "Really good" and "Such a huge help!" The project turned out to be a great team-building experience because creating effective tools requires a deep understanding of the users (in this case our own sales team), who taught us about their process and contributed requirements as the tool was being put together.
In addition, it was a fun and rewarding opportunity to contribute to the open source ecosystem. We hope you like our new toy, and will consider contributing to it. And next time you need something that doesn't exist, consider building it yourself too.
