Staging Environment

A safe sandbox to preview all changes. Deploy when you're ready.

Staging provides a layer of protection for your live documentation. Preview updates from ReadMe and changes from your team before deploying to production.

Before Staging

We built Staging to solve three main issues.

  1. The workflow for content changes gets split across:

    1. Unpublished Pages
    2. Suggested Edits
    3. Private Versions
    4. Separate Projects

    This makes it hard to get a wholistic preview of all the changes and coordinate a major release.

  2. Inability to preview project setting changes before they go live.

  3. Inability to preview ReadMe updates before they ship.

Staging is a safe sandbox to preview all changes. Nothing is published to your live documentation until you deploy from Staging to Production.

Control & Safety

Staging gives you a private way to preview the combination of changes made since the last deployment to Production including:

  • Updates to pages (including published ones)
  • Enablement of new sections (Landing Page, Tutorials, API Logs, Discussions, Changelog, etc.)
  • Testing of different project settings
  • Updates from ReadMe released every Tuesday

Everything stays in your Staging environment until you choose to deploy to Production.

👍

Resolve Potential Conflicts in Staging

When you preview the Staging environment, your updates and ReadMe's weekly updates are together. This allows you to resolve potential custom code conflicts in Staging before you deploy to Production.

How It Works

Enterprise Level Workflow

Changes from every project under your Enterprise Group are listed in the Awaiting Deploy area of the Staging section.

Element

Description

Preview link

Preview the collective changes in Staging

Deploy button

Push Staging changes to Production. (Changes can be deployed every 10 minutes)

Awaiting Deploy area

The list of all changes in Staging

Deployed area

The list of changes from prior deployments

Project Level Workflow

Any changes to your project (content, project settings, or suggested edits) will Save to Staging instead of going live. Each change will appear in the Awaiting Deploy area of the Staging section in your Enterprise Group.

The preview icon :link: has two links:

  1. Staging: Preview the collective changes awaiting deployment
  2. Production: View the live site

"View Staged Changes" will take you to the Staging section of the Enterprise Group

Landing page customizations

If you are using Staging to preview landing page customizations, make sure your landing page is enabled. Saving that goes to Staging, so it would not be public to your users until you hit Deploy. You can then continue to make changes to the landing page and previewing them on the Staging environment!

🚧

Global Landing Page redirects

If you notice that your production and staging preview links go to the same link, this is likely due to a GLP redirect (you can check this under Appearance > Global Landing Page in the parent project).

This can be fixed by changing the redirect to a relative path. For example, if the redirect is https://docs.readme.com/docs, the relative path would be /docs.

To help distinguish between Staging and Production, you'll see this banner at the bottom of the page when previewing your changes in Staging.

Deployment Privileges

Enterprise Group Admins

Project Admins

View Staging Environment

X

X

Can Deploy to Production

X

📘

Owners can also deploy to production.

To give Project Admins deployment privileges, add them to your Enterprise Group

URL Structure

We use the subdomain of your ReadMe project for your Staging URL. So if your custom domain is docs.example.com and your subdomain is example-docs, your URLs will be as follows:

Enablement

Reach out to your Enterprise CSM to enable Staging for your Enterprise Group!


Did this page help you?