Deploy to CMS SaaS

Why deployment works differently on SaaS

On CMS PaaS, deploying means shipping a .NET application to your servers. Content types, rendering code, custom logic, and configuration all travel together in a single artifact. You control the entire pipeline — CI/CD, infrastructure, rollback.

CMS SaaS inverts this model. Optimizely runs the CMS infrastructure. You deploy your content model (types, configurations) to the Optimizely cloud, and your frontend application deploys separately to your own hosting. These two deployments are independent — you can update the content model without touching the frontend, and vice versa.

This separation requires a different mental model for deployment. You are not deploying an application; you are pushing definitions to a managed platform and connecting your frontend to the content it exposes through Graph.

Cross-Product Integration

CMS

CMS SaaS deployment covers content type definitions, environment configuration, and content operations. Your frontend application (React, Next.js, etc.) deploys through your own CI/CD pipeline, not through the Optimizely deployment tools.

What you will do

1. Install and authenticate the Optimizely CLI
2. Understand the environment structure (development, staging, production)
3. Deploy content types and configuration to a development environment
4. Promote deployments from development to staging to production
5. Set up CI/CD integration for automated deployments

Install and authenticate the CLI

The Optimizely CLI is the primary tool for managing CMS SaaS deployments.

CLI installation and authentication

Terminal

bash Copy

# Install the Optimizely CLI globally
npm install -g @optimizely/cli

# Verify installation
optimizely --version

# Authenticate with your CMS SaaS account
# This opens a browser for OAuth login
optimizely login

# Verify authentication and list available environments
optimizely environments list

Authentication tokens are stored locally. For CI/CD pipelines, use API key authentication instead of browser-based login.

CI/CD authentication

Terminal

bash Copy

# Authenticate with an API key (for CI/CD environments)
export OPTIMIZELY_API_KEY="your-api-key-here"
optimizely environments list

Understand the environment structure

CMS SaaS provides isolated environments for each stage of your workflow.

Environment	Purpose	Content data	Content types
Development	Build and test new content types, try configurations	Test content only	Latest development definitions
Staging	Integration testing, content preview, UAT	Copy of production content (via sync) or separate test content	Promoted from development
Production	Live site serving real visitors	Real content	Promoted from staging

Key principle: Content types flow upward (dev to staging to production). Content data can be synced downward (production to staging) for realistic testing. Never push untested type definitions directly to production.

Deploy content types

Content type manifests are JSON files that describe your content model. You deploy them with the CLI.

Content type deployment workflow

Terminal

bash Copy

# Project structure
# my-cms-project/
#   content-types/
#     HeroBlock.json
#     LandingPage.json
#     ArticlePage.json
#   config/
#     settings.json

# Step 1: Validate manifests locally (catches errors before deployment)
optimizely content-types validate ./content-types/

# Step 2: Deploy to development environment
optimizely content-types push ./content-types/ --environment development

# Step 3: Verify deployment
optimizely content-types list --environment development

# Step 4: Check a specific type's deployed definition
optimizely content-types get HeroBlock --environment development

What happens during deployment

1. The CLI reads your manifest files and validates them against the platform schema
2. Each type definition is compared against the existing definition in the target environment
3. New types are created; modified types are updated in place
4. The CMS editor immediately reflects the changes — no restart needed

CMS

Content type updates are non-destructive. If you remove a property from a manifest, the property is hidden in the editor but existing content values are preserved. To permanently remove a property and its data, use the explicit property deletion command.

Promote across environments

Promotion is the process of moving validated definitions from one environment to the next.

Promotion workflow

Terminal

bash Copy

# After validating in development, promote to staging
optimizely content-types push ./content-types/ --environment staging

# Run integration tests against staging
# (your test suite verifies Graph queries return expected shapes)

# After staging validation, promote to production
optimizely content-types push ./content-types/ --environment production

# Verify production deployment
optimizely content-types list --environment production

Promotion checklist:

1. All content types validate without errors
2. Test content created in the development environment exercises each type
3. Visual Builder works correctly for all page types with sections
4. Graph queries from your frontend return the expected data shape
5. No breaking changes to existing published content (properties renamed or removed)

Manage environment configuration

Beyond content types, environments have their own configuration for features like localization, webhooks, and Graph settings.

Environment configuration

Terminal

bash Copy

# Export current configuration from an environment
optimizely config export --environment development > config/dev-settings.json

# Push configuration to an environment
optimizely config push ./config/settings.json --environment development

# Sync content from production to staging for realistic testing
optimizely content sync --from production --to staging

Set up CI/CD integration

Automate deployments by integrating the CLI into your CI/CD pipeline.

GitHub Actions deployment

GitHub Actions

yaml Copy

name: Deploy CMS Content Types

on:
  push:
    branches: [main]
    paths:
      - 'content-types/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Optimizely CLI
        run: npm install -g @optimizely/cli

      - name: Validate content types
        run: optimizely content-types validate ./content-types/

      - name: Deploy to staging
        env:
          OPTIMIZELY_API_KEY: ${{ secrets.OPTIMIZELY_API_KEY_STAGING }}
        run: optimizely content-types push ./content-types/ --environment staging

      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        env:
          OPTIMIZELY_API_KEY: ${{ secrets.OPTIMIZELY_API_KEY_PRODUCTION }}
        run: optimizely content-types push ./content-types/ --environment production

CI/CD best practices:

• Store API keys as secrets — never commit them to source control
• Validate before deploying — fail the pipeline early if manifests have errors
• Deploy to staging first — even in automated pipelines, run integration tests before production
• Use branch protection — require pull request reviews for changes to content type manifests
• Version your manifests — track content type definitions in Git alongside your frontend code

Rollback strategy

If a deployment introduces problems:

1. Revert the manifest change in Git and redeploy the previous version
2. Content type updates are non-destructive — reverting a property addition hides the property but does not delete content
3. Breaking changes (removing a required property that content depends on) should be handled with a migration plan, not a rollback

There is no one-click “undo deployment” button. Your rollback strategy is your Git history plus a redeploy of the previous manifest version.

Common issues

Issue	Cause	Fix
CLI authentication fails	Expired token or invalid API key	Run optimizely login again, or regenerate the API key
Push fails with conflict	Two developers pushed conflicting type changes	Pull the latest deployed definition, merge changes, push again
Types not appearing in editor	Deployment targeted wrong environment	Verify with environments list and content-types list
Graph queries return old schema	Graph schema cache not refreshed	Wait a few minutes for cache invalidation, or trigger a manual refresh
Content sync fails	Insufficient permissions on source environment	Ensure your API key has read access on the source and write access on the target

Related content

Continue your journey with these related pages.

📖Understand the concepts

• CMS SaaS vs CMS PaaS
• Content Delivery with Graph

🔧Follow a guide

• Define Content Types for CMS SaaS
• Visual Builder Basics
• Set Up Graph