Amedee

Maintaining documentation for Ansible roles can be a tedious and easily neglected task. As roles evolve, variable names change, and new tasks are added, it is easy for the README.md files to fall out of sync. To prevent this and keep documentation continuously up to date, I wrote a GitHub Actions workflow that automatically generates and formats documentation for all Ansible roles in my repository. Even better: it writes its own commit messages using AI.

Let me walk you through why I created this workflow, how it works, and what problems it solves.

🤔 Why Automate Role Documentation?

Ansible roles are modular, reusable components. Good roles include well-structured documentation—at the very least, variable descriptions, usage examples, and explanations of defaults.

However, writing documentation manually introduces several problems:

• Inconsistency: Humans forget things. Updates to a role do not always get mirrored in its documentation.
• Wasted time: Writing boilerplate documentation by hand is inefficient.
• Error-prone: Manually copying variable names and descriptions invites typos and outdated content.

Enter ansible-doctor: a tool that analyzes roles and generates structured documentation automatically. Once I had that, it made perfect sense to automate its execution using GitHub Actions.

⚙️ How the Workflow Works

Here is the high-level overview of what the workflow does:

1. Triggers:
   • It can be run manually via workflow_dispatch.
   • It is also designed to be reusable in other workflows via workflow_call.
2. Concurrency and Permissions:
   • Uses concurrency to ensure that only one documentation run per branch is active at a time.
   • Grants minimal permissions needed to write to the repository and generate OIDC tokens.
3. Steps:
   • ✅ Check out the code.
   • 🐍 Set up Python and install ansible-doctor.
   • 📄 Generate documentation with ansible-doctor --recursive roles.
   • 🧼 Format the resulting Markdown using Prettier to ensure consistency.
   • 🤖 Configure Git with a bot identity.
   • 🔍 Detect whether any .md files changed.
   • 🧠 Generate a commit message using AI, powered by OpenRouter.ai and a small open-source model (mistralai/devstral-small:free).
   • 💾 Commit and push the changes if there are any.

🧠 AI-Generated Commit Messages

Why use AI for commit messages?

• I want my commits to be meaningful, concise, and nicely formatted.
• The AI model is given a diff of the staged Markdown changes (up to 3000 characters) and asked to:
  • Keep it under 72 characters.
  • Start with an emoji.
  • Summarize the nature of the documentation update.

This is a small but elegant example of how LLMs can reduce repetitive work and make commits cleaner and more expressive.

Fallbacks are in place: if the AI fails to generate a message, the workflow defaults to a generic 📝 Update Ansible role documentation.

🌍 A Universal Pattern for Automated Docs

Although this workflow is focused on Ansible, the underlying pattern is not specific to Ansible at all. You can apply the same approach to any programming language or ecosystem that supports documentation generation based on inline annotations, comments, or code structure.

The general steps are:

1. Write documentation annotations in your code (e.g. JSDoc, Doxygen, Python docstrings, Rust doc comments, etc.).
2. Run a documentation generator, such as:
   • javadoc for Java
   • jsdoc for JavaScript
   • sphinx for Python
   • rustdoc for Rust
   • godoc for Go
   • doxygen for C/C++
3. Generate a commit message from the diff using an LLM.
4. Commit and push the updated documentation.

This automation pattern works best in projects where:

• Documentation is stored in version control.
• Changes to documentation should be traceable.
• Developers want to reduce the overhead of writing and committing docs manually.

🔐 A Note on OpenRouter API Keys

The AI step relies on OpenRouter.ai to provide access to language models. To keep your API key secure, it is passed via secrets.OPENROUTER_API_KEY, which is required when calling this workflow. I recommend generating a dedicated, rate-limited key for GitHub Actions use.

🧪 Try It Yourself

If you are working with Ansible roles—or any codebase with structured documentation—and want to keep your docs fresh and AI-assisted, this workflow might be useful for you too. Feel free to copy and adapt it for your own projects. You can find the full source in my GitHub repository.

Let the robots do the boring work, so you can focus on writing better code.

💬 Feedback?

If you have ideas to improve this workflow or want to share your own automation tricks, feel free to leave a comment or reach out on Mastodon: @amedee@lou.lt.

Happy automating!