Streamlining GitHub Actions Development with Self-Documenting GitHub Actions
In my recent project, I’ve focused on streamlining the development workflow for Cisco Collaboration by migrating thousands of repository build processes to GitHub Actions. This transition has brought numerous benefits in terms of automation and efficiency, but it also presented a challenge in keeping in-development GitHub Action documentation up-to-date and ensuring consistency across all actions.
One area that became a repetitive drain on productivity was documenting actions, specifically details like inputs, outputs, environment variable usage, and other metadata values of interest. The lack of consistency was the only consistency; every existing and even newly created action had either no documentation, or had its own unique way to document the action.
There was zero consistency on how GitHub Action documentation should be constructed or maintained, leading to frustrating time spent debugging issues related to renamed or removed inputs that could have been avoided with documentation.
It became very apparent that an auto-documentation tool could save boatloads of time by automating these updates.
I started a GitHub Action aimed to eliminate the required manual effort to ensure, at minimum, consistent essential documentation is kept up-to-date. This GitHub Action allows developers to focus more on innovation rather than time spent hunting yaml files without a consistent layout to find the requirements of the action by its “inputs” and “outputs”.
While the solution isn’t fully cleaned up for production use yet, it’s progressing steadily. The current version of my GitHub Action for GitHub Action self-documentation can be found here:
GitHub - coderrob/update-action-readme
The coderrob/update-action-readme’s own README.md was generated using the tool to provide a demonstration of what is possible.
After all, code should be self documenting, right?
I’m excited about the potential to enhance productivity by ensuring that documentation is a consistent seamless part of the workflow rather than an afterthought, I’m hoping this will help others improve their overall efficiency too. I have no shortage of ideas, but I outlined the remaining TODO.md list for the PoC before I try to publish to the GitHub Actions marketplace.
Thoughts, requests, or any feedback are always welcome.
Just let me know how I can help!