On GitHub there are the GitHub issues, and they have become quite powerful over time. Just recently GitHub added the capability to show related issues, pin issues to repositories and to move them between repositories.
One important tool to manage issues on GitHub are labels, those nicely colored badges you can add to issues to get a better overview, to filter lists and queries, or to build further automation such as the presentation of good first issues to people new to the project.
If you have a lot of labels it tends to become a bit of effort to manage them well, especially if you want to keep colors consistent and descriptions up to date. It becomes even more effort when you try to do so across different repositories. We have all seen the psychedelic potpourri of colorful labels which tends to happen when you use labels generously.
Last year I saw Mitchell Hashimoto's excellent talk about anything as code at the Open Source Datacenter Conference in Berlin. He showed there how to use Terraform to manage infrastructure as code beyond the typical management of computing infrastructure such as servers or networks. He showed how to use it for more administrative tasks such as managing teams on GitHub.
This is a great approach because it replaces clicking around in a user interface by a more programming-like approach of maintaining configurations, preferably version controlled, and applying the same rules on them as on code. So you can do pull requests, review changes, have the history of what happened in git, run tests and other automation easily, etc.
The GitHub provider for Terraform also handles labels so I thought I would give it a try to manage labels as code. Directly doing this in the Terraform configuration is possible but it's a bit cumbersome and limited in what you can do with the data in this format. So I decided to put the data into a good old YAML file and writing a bit of Python code to deal with it.
The result is beautiful-labels, a small tool to manage GitHub labels from a YAML description via Terraform. It scans your repository for existing labels and their data, creates a YAML description from it, and then provides you the tools to turn it into a Terraform configuration.
Terraform is great in handling the state of things in the cloud, it takes care of operating the API in an effective way, figuring out what needs to be updated, and gives the user control, for example by providing a dry run which tells what would change without applying the changes yet. This is all quite convenient and powerful.
One thing beautiful-labels is supposed to make easy is the management of label colors. In addition to the convenience of managing them in YAML instead of having to use the UI, it also adds the option to generate an overview of the labels as SVG, nicely grouped in categories. This helps in grouping things together using colors and generally can augment documentation about how you intend labels to be used.
The tool is in an early state but it works. I use it to manage the labels in the inqlude repository on GitHub.
You could add another step of automation by letting CI run Terraform on commits to the YAML file. Maybe something to try for the future. As managing labels is not something you usually do on a daily basis, some manual step might also be good enough.
One caveat with labels is that GitHub uses the name of the label as identifier. That usually works great but can be a bit tricky when changing the name of a label. For this case I recommend to do it in the GitHub UI for now.
There are some other approaches how to do this kind of stuff. One of them is labeler which is a nice tool written in Go to manage labels from a YAML description. It directly operates the GitHub API. The advantage is that it's self-contained but it lacks the power of Terraform in terms of state management. Another is Zach Dunn's post "How we organize GitHub issue: A simple styleguide for tagging" which introduces the notion of color-coded categories.
It's wonderful when pieces come together, such as the GitHub API, Terraform, YAML, git, and people writing open source code around that. They result in a way to beautifully manage labels without having to put in too much effort.
If you have feedback or input please don't hesitate to drop me a line. I would be happy if beautiful-labels would be useful for you as well. Let me know how it goes. :-)
No comments:
Post a Comment