Zero Review Workflow for Docs-Only MRs

Documentation is the unsung hero of software development, yet the friction in updating it often leads to the very thing teams dread most: outdated and unreliable information that nobody trusts.

The Documentation Storage Dilemma 📚

Every software team needs to maintain documentation. Whether it’s guides for end users, technical explanations of complex architectures, onboarding materials for new developers, or even prompt libraries for your LLMs — the question remains: where should all this knowledge live?

Two dominant schools of thought exist, each with compelling advantages and frustrating drawbacks.

Option 1: Version-Controlled Documentation ✅

The first approach keeps documentation versioned inside your code repository, typically as Markdown or reStructuredText files. This method, popular in open source projects, offers a clean, structured approach with several benefits:

• Documentation changes can be tracked alongside code changes
• Version history is maintained automatically
• Documentation accuracy can be enforced through CI/CD processes
• Everything lives in one place, reducing context switching

However, this approach isn’t without flaws. While theoretically documentation and code should stay in sync, reality often differs. The biggest pain point? The update process itself. Making even minor documentation fixes requires creating pull requests, waiting for code reviews, and navigating the same quality gates as production code changes.

This friction often kills the “Boy Scout Rule” — the practice of improving documentation whenever you notice issues, leaving it better than you found it.

Option 2: External Knowledge Bases 📦

The alternative approach uses dedicated knowledge management platforms like Notion, Confluence, or GitBook. These tools offer significant advantages:

• Superior editing experience with rich text formatting
• No technical barrier for non-developers to contribute
• Real-time collaboration capabilities
• Immediate updates without review processes
• Built-in organization and search functionality

The glaring downside? These systems exist completely separate from your codebase. There’s no inherent connection between code changes and documentation updates, making it easy for the two to drift apart over time.

Getting the Best of Both Worlds: Auto-Approved Documentation Changes 😌

What if we could maintain documentation in our code repositories but remove the friction that discourages frequent updates?

Enter the concept of auto-approving documentation changes. The core idea is simple but powerful: configure your CI system to automatically approve pull requests that only modify documentation files.

This approach preserves all the benefits of version-controlled documentation while eliminating the bottleneck of human review for straightforward documentation updates.

You might want to maintain stricter controls for user-facing documentation, API references, or legal content, where accuracy is critical and mistakes could have significant consequences.

Potential Pitfalls ⚠️

Before implementing auto-approval, consider these challenges:

1. Trust requirements: This system assumes team members won’t abuse the auto-approval mechanism.
2. Scope creep: You’ll need mechanisms to detect when non-documentation changes are added to a previously documentation-only PR.
3. Quality concerns: Without human review, documentation quality depends entirely on the author’s diligence.
4. Security considerations: Ensure sensitive information doesn’t accidentally get committed through documentation updates.

🛠️ Auto-Approving Documentation-Only MRs in GitLab

In GitLab, you can auto-approve documentation-only merge requests by combining CI jobs with the GitLab API:

Detect Documentation-Only Changes

Add a job in your .gitlab-ci.ymlthat runs on merge requests and checks if all modified files match your documentation pattern (e.g., files in /docs/or with .mdextensions).

Approve via GitLab API

If the MR passes the check, use a script to call the GitLab API’s /approveendpoint. This requires:

• A personal access token with API permissions
• Storing the token as a CI/CD secret
• A curl command to approve the MR automatically

This setup reduces review bottlenecks while keeping docs versioned and in sync with your codebase.