Integrate ReadMe Enterprise into Your Workflow
Set up branching, Docs as Code, or hybrid workflows to keep documentation versioned and governed across every product and team in your organization.
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
Branching (Documentation-focused)
Best for teams that:
- Manage documentation across multiple products / Groups and require isolated review.
- Are documentation-heavy
- Work with multiple contributors
- Release frequently (weekly or faster)
- Review content asynchronously
How it works
At Enterprise scale, branches let each product team ship on its own cadence while still rolling up under shared Group-level governance. 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
- Publish content on your own schedule
If your team prefers writing in Markdown or managing docs in source control, syncing ReadMe with GitHub (including GitHub Enterprise) or GitLab unlocks a more reviewable workflow.
- Docs live in your repo as
.mdfiles (MDX supported) - Changes pushed to repo appear in ReadMe
- Changes made in ReadMe sync back to repo
- Branches sync too: create them in your repo or ReadMe
Features to set up
- Bi-directional sync with GitHub (including GHES) 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. (Bi-Directional Sync with GitHub Enterprise is available on the Enterprise plan)
- Groups: The Enterprise construct for managing multiple projects under shared roles, dashboards, and governance.
Governance at Scale
Enterprise organizations manage documentation across many teams and products, raising the stakes for access control and auditability. ReadMe Enterprise supports:
- Audit Logs track changes across projects and Groups
- Permission auditing to review who has access to what, across every project in your organization
FAQ
What does the repository structure look like?
/docs-> Markdown documentation/openapi-> OpenAPI definitions/scripts-> CI/CD helpers
Updated 2 days ago