# Environments, publishing, and promotion strategies

### About this export

| Field | Value |
| --- | --- |
| **content_type** | lesson |
| **platform** | contentstack-academy |
| **source_url** | https://www.contentstack.com/academy/courses/apis-and-developer-tooling/environments-publishing-and-promotion-strategies |
| **course_slug** | apis-and-developer-tooling |
| **lesson_slug** | environments-publishing-and-promotion-strategies |
| **markdown_file_url** | /academy/md/courses/apis-and-developer-tooling/environments-publishing-and-promotion-strategies.md |
| **generated_at** | 2026-08-03T11:49:31.019Z |

> Part of **[APIs and Developer Tooling](https://www.contentstack.com/academy/courses/apis-and-developer-tooling)** on Contentstack Academy. **Academy MD v3** — structured for retrieval; no quiz or assessment keys.

<!-- ai_metadata: {"lesson_id":"13","type":"text","duration_minutes":1,"topics":["Environments","publishing","and","promotion","strategies"]} -->

#### Lesson text

# Environments, publishing, and promotion strategies

> **TL;DR**
> 
> *   Environments are deployment targets (development, staging, production), not code branches -- Contentstack has a separate branching model for parallel content work.
> *   Each environment gets its own delivery token; use publish rules to restrict which roles can publish to sensitive environments like production.
> *   Publish assets before the entries that reference them to avoid broken references on the target environment.

> **Prerequisites**
> 
> This module assumes comfort with CLI/terminal usage and basic CI/CD concepts (build pipelines, environment variables, deploy hooks). If you're new to these, review your CI/CD platform's getting-started guide first.

In Contentstack, an environment is a deployment target, not a code branch. This distinction trips up developers who come from git-centric workflows where "environment" and "branch" are loosely interchangeable. They are not interchangeable here. Contentstack has a first-class branching model for content (covered elsewhere in this course), and environments serve a completely different purpose: they represent the destinations where published content becomes available for delivery.

Getting environments right is foundational. Every delivery token is scoped to an environment. Every publish action targets an environment. Every frontend deployment maps to an environment. If your environment strategy is muddled, your entire content delivery pipeline inherits that confusion.

## What environments represent

An environment in Contentstack defines a named deployment target with associated configuration:

*   Name: a human-readable identifier like development, staging, or production.
*   Base URL: the URL of the frontend application that consumes published content from this environment. For an e-commerce site, this might be https://shop.example.com for production and https://staging.shop.example.com for staging.
*   Preview URL: an optional URL used by Live Preview to render draft content in the context of a specific environment.
*   Server or region settings: additional configuration depending on your Contentstack plan and region.

Environments are stack-level resources. When you create a stack for your e-commerce platform, you define environments that match your deployment topology. A typical three-environment setup might look like this:

Environment

Base URL

Purpose

development

[https://dev.shop.example.com](https://dev.shop.example.com/)

Developer integration testing

staging

[https://staging.shop.example.com](https://staging.shop.example.com/)

QA, stakeholder review, UAT

production

[https://shop.example.com](https://shop.example.com/)

Live customer-facing storefront

Each environment operates independently in terms of published content state. An entry published to staging is not automatically available in production. This is by design: it gives teams explicit control over what content reaches which audience.

## Each environment gets its own delivery token

This is where environment strategy meets security architecture. Contentstack issues delivery tokens per environment. Your production frontend uses a delivery token scoped to the production environment. Your staging frontend uses a different token scoped to staging.

// environment-tokens.ts  -  e-commerce storefront configuration
const environmentConfig = {
  development: {
    deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_DEV,
    apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY,
    environment: "development",
  },
  staging: {
    deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_STAGING,
    apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY,
    environment: "staging",
  },
  production: {
    deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_PROD,
    apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY,
    environment: "production",
  },
};

export function getStackConfig(env: keyof typeof environmentConfig) {
  return environmentConfig\[env\];
}

The security implication is direct: if a staging delivery token leaks, production content is unaffected. Token isolation per environment limits blast radius. This also means that rotating tokens can happen per environment without disrupting unrelated deployment targets.

## Publishing to environments

Publishing is the act of making content available through the Content Delivery API for a specific environment. Until an entry or asset is published to an environment, it exists only in draft state and is accessible only through the Content Management API or Preview endpoints.

### Single-environment publish

The most common publish action targets one environment at a time. An editor working on a new product listing for the e-commerce catalog publishes to development first for developer verification, then promotes to staging for QA review.

### Multi-environment publish

Contentstack also supports publishing an entry to multiple environments simultaneously. This is useful when content has been fully vetted and needs to go live across several targets at once. For example, publishing a critical pricing update to both staging and production at the same time. However, multi-environment publish should be used deliberately. In most mature workflows, you want content to move through environments sequentially, not skip stages.

### Publishing entries vs publishing assets

Entries and assets follow the same environment-scoped publishing model, but they have different operational characteristics:

*   Entries carry references to other entries and assets. Publishing an entry does not automatically publish its referenced content. If an entry references an asset that has not been published to the target environment, the delivery response will contain a broken reference.
*   Assets are independently publishable. A product image can be published to production before or after the product entry that references it, but the ordering matters for frontend rendering correctness.

A disciplined approach is to publish assets before the entries that reference them. For the e-commerce storefront, this means publishing product images to staging before publishing the product entries that display those images.

## The publish queue

Every publish action in Contentstack enters a publish queue. The queue processes publish requests asynchronously, which means that clicking "Publish" in the UI or triggering a publish via CMA does not guarantee instant availability on the CDN.

The publish queue provides several operational benefits:

*   Rate smoothing: large bulk-publish operations do not overwhelm the delivery infrastructure.
*   Visibility: the queue shows pending, in-progress, and completed publish actions.
*   Error surfacing: failed publishes appear in the queue with actionable error details.

For the e-commerce site running a seasonal catalog refresh that involves publishing hundreds of product entries and their associated assets, the publish queue becomes operationally critical. Teams can monitor progress, identify failures, and retry individual items without re-triggering the entire batch.

You can inspect the publish queue programmatically through the CMA:

// Check publish queue status for a bulk operation
const response = await fetch(
  "https://api.contentstack.io/v3/publish-queue",
  {
    headers: {
      api\_key: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!,
      authorization: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_MANAGEMENT\_TOKEN!,
    },
  }
);

const queue = await response.json();
queue.queue.forEach((item: any) => {
  console.log(
    \`${item.entry?.title || item.asset?.title} → ${item.environment} \[${item.status}\]\`
  );
});

## Promotion strategy: development to staging to production

A promotion strategy defines how content moves through environments. The standard pattern mirrors application deployment pipelines:

1.  Development: content is authored and initially published here. Developers integrate against this environment. Broken content, experimental entries, and work-in-progress all live here.
2.  Staging: content that passes initial review is promoted to staging. This environment is used for stakeholder sign-off, QA testing, and user acceptance. The staging frontend should closely mirror production behavior.
3.  Production: only fully approved content is published here. This is what end customers see.

Promotion can be manual (editors republish to the next environment) or governed by workflow and publish rules that enforce stage gates. In a well-run e-commerce operation, a new product listing might follow this path:

*   Editor creates the product entry and publishes to development.
*   Developer verifies the entry renders correctly in the storefront.
*   Editor publishes to staging for merchandising team review.
*   After approval, a senior editor publishes to production.

Each publish action is explicit and auditable. Content does not drift between environments without intentional action.

## Publish rules: governing who can publish where

Contentstack supports publish rules that restrict which roles can publish to which environments. This is a governance mechanism, not just a convenience.

For an e-commerce platform with multiple teams, publish rules might look like:

*   Content Authors can publish to development only.
*   Content Managers can publish to development and staging.
*   Senior Editors (or a Release Manager role) can publish to production.

Publish rules enforce the promotion strategy structurally. Without them, any editor with publish permissions could accidentally push an unreviewed product entry directly to the live storefront.

Publish rules work alongside workflow stages. A common pattern combines them: workflow gates ensure content goes through review steps, and publish rules ensure only authorized roles can execute the final publish action to sensitive environments.

## How environments map to frontend deployment targets

The mapping between Contentstack environments and frontend deployments should be explicit and documented. For the e-commerce storefront built on Next.js and deployed via Vercel:

Contentstack environment

Frontend deployment

Vercel environment

Delivery token source

development

dev.shop.example.com

Preview

NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_DEV

staging

staging.shop.example.com

Preview (staging)

NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_STAGING

production

shop.example.com

Production

NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN\_PROD

Each Vercel environment injects the correct delivery token. The frontend code itself does not change between environments; only the token and the Contentstack environment name differ. This is the same principle as twelve-factor app configuration: environment-specific values live in environment variables, not in code.

// next.config.ts  -  environment-aware Contentstack configuration
import contentstack from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!,
  deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN!,
  environment: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_ENVIRONMENT!,
});

export default stack;

The NEXT\_PUBLIC\_CONTENTSTACK\_ENVIRONMENT variable resolves to development, staging, or production depending on where the frontend is deployed. No conditional logic. No hardcoded environment names.

## Common mistakes

### Mistake 1: using environments as branches

Contentstack has a dedicated branching system for parallel content development. Environments are not branches. If you create an environment called feature-new-checkout to isolate content changes, you are misusing the system. Use a Contentstack branch instead, then publish from that branch to the appropriate environment when ready.

> **Common pitfall:**
> 
> Publishing directly to production without staging verification saves a few minutes but can cost hours of incident response when broken content, missing references, or layout issues reach customers.

### Mistake 2: publishing to production without staging verification

Skipping the staging step saves a few minutes and costs hours when broken content reaches customers. Even for "simple text changes," the staging environment exists to catch rendering issues, broken references, and layout problems that are invisible in the CMS entry editor.

### Mistake 3: ignoring asset publish order

Publishing a product entry that references an unpublished hero image produces a broken storefront page. Always verify that referenced assets are published to the target environment before or alongside the entries that depend on them.

### Mistake 4: sharing delivery tokens across environments

Using the production delivery token in your staging frontend defeats the purpose of environment isolation. Each frontend deployment must use the token scoped to its corresponding Contentstack environment.

## Summary

Environments in Contentstack are deployment targets with dedicated delivery tokens, independent publish states, and governance controls. A disciplined promotion strategy moves content from development through staging to production, with publish rules restricting who can act at each stage. The publish queue provides visibility into asynchronous publish operations, and the mapping between CMS environments and frontend deployments should be explicit, documented, and enforced through environment variables.

The key insight is that environments are about where content is delivered, not about content versioning or parallel development. Contentstack branches handle those concerns. Conflating the two leads to architectural confusion that is painful to unwind later.

#### Key takeaways

- Connect **Environments, publishing, and promotion strategies** back to your stack configuration before moving to the next module.
- Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment.
- Re-read the delivery versus management boundary for anything you changed in the entry model.

## Supplement for indexing

### Content summary

Environments, publishing, and promotion strategies. Environments, publishing, and promotion strategies TL;DR Environments are deployment targets (development, staging, production), not code branches -- Contentstack has a separate branching model for parallel content work. Each environment gets its own delivery token; use publish rules to restrict which roles can publish to sensitive environments like production. Publish assets before the entries that reference them to avoid broken references on the target environment. Prerequisites This module assumes comfort with CLI/terminal usage and basic CI/CD concepts (build pipelines, environment variables, deploy hooks). If you're new to these, review your CI/CD platform's getting-started guide first.

### Retrieval tags

- Environments
- publishing
- and
- promotion
- strategies
- apis-and-developer-tooling
- lesson 13
- Environments, publishing, and promotion strategies
- apis-and-developer-tooling lesson

### Indexing notes

Index this lesson as a primary chunk tagged with lesson_id "13" and topics: [Environments, publishing, and, promotion, strategies].
Parent course slug: apis-and-developer-tooling. Use asset_references URLs as thumbnail hints in search results when present.
Never surface LMS quiz content or assessment answers from this file.

### Asset references

_No image or video thumbnail URLs were extracted._

### External links

| Label | URL |
| --- | --- |
| Contentstack Academy home | `https://www.contentstack.com/academy/` |
| Training instance setup | `https://www.contentstack.com/academy/training-instance` |
| Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` |
| Contentstack documentation | `https://www.contentstack.com/docs/` |
| https://dev.shop.example.com | `https://dev.shop.example.com/` |
| https://staging.shop.example.com | `https://staging.shop.example.com/` |
| https://shop.example.com | `https://shop.example.com/` |