Integrating ReadMe into Your Workflow

As documentation scales, it requires the same rigor as product development. Without a defined workflow, content quickly falls out of sync with releases.

This guide documents the standard documentation workflows used by enterprise teams integrating ReadMe into CI/CD pipelines. These workflows are designed to:

Keep documentation versioned with releases
Enforce clear ownership and review processes
Scale across teams, products, and content

If you’re setting this up for the first time, follow the recommended workflow below. It reflects how most organizations successfully operate at scale.

Workflow Patterns

Recommended: Branching (Documentation-focused)

Best for teams

Are documentation-heavy
Work with multiple contributors
Release frequently (weekly or faster)
Review content asynchronously

How it works

Branches let you create and review content in isolation without affecting the live version of your documentation. Teams can:

Work on multiple updates in parallel
Save changes without publishing
Review updates before merging them live
Merge content on your own schedule

If your team prefers writing in Markdown or managing docs in source control, syncing ReadMe with GitHub or Gitlab unlocks a more robust, reviewable workflow.

Docs live in your GitHub repo as.md files (MDX supported)
Changes pushed to GitHub appear in ReadMe
Changes made in ReadMe sync back to GitHub
Branches sync too: create them in GitHub or ReadMe

Features to set up

Bi-directional sync supports GitHub or GitLab (recommended)

Learn more: Branching for Enterprise.

User Roles

Use ReadMe's user roles to control access to Group-level dashboards and projects for all teammates. Roles determine where teammates can make changes:

Admin: Full access to all dashboards and projects.
Editors: Can create and edit hub content; no access to Group dashboards.
Viewers: Can view documentation only; no editing permissions and no access to Group dashboards.
Custom: Assign different roles per project to fine-tune access.

Key Terms

These are building blocks shared across all setups:

ReadMe CLI (rdme): Automates OpenAPI validation, uploads, and documentation updates from CI/CD pipelines.
Git, GitHub, GitLab: Acts as the source of truth for OpenAPI specifications and Markdown documentation (optional).
CI/CD (GitHub Actions, GitLab CI, etc): Runs validation, linting, and publishing steps on pull requests and merges.
Bi-Directional Sync: Keeps content aligned when edits happen in both Git and the ReadMe Editor.

FAQ

What does the repository structure look like?

/docs -> Markdown documentation
/openapi -> OpenAPI definitions
/scripts -> CI/CD helpers