---
title: "Ship on Launch"
url: "https://developers.contentstack.com/paths/ship-on-launch"
type: "path_full"
level: "intermediate"
outcome: "A Launch project deployed from CI, with redirects, edge logic and cache revalidation wired to content changes."
steps:
  - "https://developers.contentstack.com/guides/deploy-from-ci-with-the-launch-cli-and-api"
  - "https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching"
  - "https://developers.contentstack.com/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch"
updated: "2026-11-15T11:47:33.912Z"
---

# Ship on Launch

- **Level:** Intermediate
- **Steps:** 3
- **Overview:** https://developers.contentstack.com/paths/ship-on-launch.md

---

Take a Contentstack site from a manual deploy to a CI-driven Launch project with edge routing, edge functions and a cache strategy you can reason about.

**You'll end up with:** A Launch project deployed from CI, with redirects, edge logic and cache revalidation wired to content changes.

## Table of Contents

1. Deploy from CI with the Launch CLI, REST API and deploy hooks
2. Edge functions, redirects and caching on Launch
3. Revalidate, prime or redeploy? Picking the right cache lever on Launch


---

## Step 1: Deploy from CI with the Launch CLI, REST API and deploy hooks

- **Source:** https://developers.contentstack.com/guides/deploy-from-ci-with-the-launch-cli-and-api
- **Checkpoint:** Your project deploys from CI using the Launch CLI or a deploy hook.

- **Authors:** Tim Benniks
- **Published:** 2026-11-19T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:53.489Z
- **Level:** Advanced
- **Intent:** Ship
- **Tags:** cli, api, automation

---

Auto deploy on commit is the right default for preview and staging environments. For production, most teams want the pipeline to decide: run the tests, deploy only the commit that passed, wait for Launch to finish, check the live site, and undo the release when the check fails. Launch gives you three ways to drive that from CI, and you will usually combine two of them.

This guide uses GitHub Actions, but every step is a shell command, so it moves to GitLab CI, CircleCI or Azure Pipelines without changes.

## What you'll learn

- When to use a deploy hook, the Launch CLI plugin or the Launch REST API


- How to stop Launch and your pipeline from deploying the same commit twice


- How to trigger a deployment for an exact commit and wait for it to go live


- How to roll back automatically when a smoke test fails


- Which authentication limits shape the pipeline



## Pick a trigger

Option

Good for

Authentication

Deploy hook

Git-based projects, CMS-triggered rebuilds

The secret URL itself

Launch CLI plugin

File upload projects, teams already using csdx

Login with a Contentstack user

Launch REST API

Status checks, logs, rollbacks, uploaded builds

OAuth bearer token, or authtoken plus organization_uid

The pipeline in this guide triggers with a deploy hook and uses the REST API for everything after that. The CLI section shows the alternative when you build outside Launch or prefer one tool.

## Turn off auto deploy on production

Launch concept: auto deploy is on by default for every Git-based environment. Each push to the connected branch starts a deployment.

If you leave it on and add a CI deploy, every merge triggers two deployments. Launch handles that without breaking anything, because it skips queued deployments in between and only the latest takes effect, but your pipeline then waits on a deployment that may never run. Turn auto deploy off for the production environment in its settings, and keep it on for preview environments.

Projects created by file upload don't have auto deploy, so there is nothing to turn off.

## Trigger with a deploy hook

Launch concept: a deploy hook is a unique URL per environment. A POST to it starts a deployment.

Create one in Launch: open the environment Settings, go to Deploy Hooks, click + New Deploy Hook and copy the URL. Store it as a CI secret, for example LAUNCH_DEPLOY_HOOK_URL. Anyone with the URL can deploy your site, so treat it like a password.

```bash
curl -X POST "$LAUNCH_DEPLOY_HOOK_URL?commit=$GITHUB_SHA"
```

```json
{ "message": "Deployment triggered successfully" }
```

The commit parameter takes a full SHA or its first seven characters, and pins the deployment to the commit your tests ran against. Without it, Launch deploys the latest commit on the connected branch, which may be newer than the one you tested. Leave commit out for file upload projects.

The same URL works as a Contentstack webhook target if you want a full rebuild on publish. For content changes, revalidating the CDN is usually cheaper than a rebuild; see [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming).

## Deploy with the Launch CLI

The Launch commands live in a separate plugin, @contentstack/cli-launch. Recent versions of the Contentstack CLI don't bundle it, and running csdx launch without it fails. Install it in CI before any launch command.

The CLI needs a config file that points at your project and environment. Create it once and commit it:

```json
{
  "project": {
    "uid": "<project-uid>",
    "name": "marketing-site",
    "projectType": "GITHUB",
    "organizationUid": "<organization-uid>",
    "environments": [
      { "uid": "<environment-uid>", "name": "production", "frameworkPreset": "NEXTJS" }
    ],
    "deployments": [{ "uid": "<any-deployment-uid-in-that-environment>" }]
  }
}
```

Use FILEUPLOAD as projectType for file upload projects. You can read the UIDs from the x-project-uid, x-environment-uid, x-org-uid and x-deployment-uid response headers of your deployed site.

Then the CI steps are:

```bash
npm install -g @contentstack/cli
csdx plugins:install @contentstack/cli-launch
csdx config:set:region NA
csdx auth:login --username "$CS_USERNAME" --password "$CS_PASSWORD"
csdx launch --config ./.cs-launch.json --environment production --redeploy-latest
```

--redeploy-latest redeploys the latest commit for Git projects, and uploads the current files for file upload projects. That makes the CLI the easiest way to ship a build that CI produced: build, then run csdx launch from the folder. Use --redeploy-last-upload to redeploy the previous upload instead. The two flags can't be combined.

The CLI exits with a non-zero status when the deployment fails, so the job fails with it.

Watch out: the Launch plugin supports login-based authentication only. Users who sign in through an identity provider in an SSO-enabled organization can't log in this way. Use a dedicated CI user that is allowed to sign in without SSO, and keep its credentials in CI secrets.

## Use the REST API

The Launch API covers what happens after the trigger: status, logs and rollbacks. The base URL depends on your region, for example https://launch-api.contentstack.com for AWS NA or https://eu-launch-api.contentstack.com for AWS EU.

Send one of these:

- Authorization: Bearer <token> with an OAuth token. A machine-to-machine app token works for reading deployments and logs, revalidating the cache and deploying uploaded files. See [OAuth and machine-to-machine apps](/guides/build-your-first-developer-hub-app/oauth-and-machine-to-machine-apps) for how to get one.


- authtoken and organization_uid headers with a user authtoken.



The calls this pipeline needs:

Call

Endpoint

List deployments

GET /projects/{project_uid}/environments/{environment_uid}/deployments

Get one deployment

GET /projects/{project_uid}/environments/{environment_uid}/deployments/{deployment_uid}

Create a deployment

POST /projects/{project_uid}/environments/{environment_uid}/deployments

Roll back

POST /projects/{project_uid}/environments/{environment_uid}/deployments/rollback

Create a deployment accepts { "commitHash": "<sha>" } for Git projects, but only with a user token. With an app token, use a deploy hook for Git projects, or the upload flow for built artifacts: request a signed upload URL, upload your ZIP to it, then create a deployment with { "uploadUid": "<uid>" }.

A deployment moves through QUEUED, DEPLOYING and LIVE. It ends in FAILED, CANCELLED or SKIPPED if it doesn't go live. When a new deployment goes live, the previous one becomes ARCHIVED.

The API allows 10 requests per second per organization. Poll every 10 to 15 seconds, not in a tight loop.

## Build the GitHub Actions workflow

flowchart LR  A[Push to main] --> B[Tests]  B --> C[Record current LIVE deployment]  C --> D[POST deploy hook with commit SHA]  D --> E{Poll status}  E -->|LIVE| F[Smoke test]  E -->|FAILED or CANCELLED| X[Fail the job]  F -->|pass| G[Done]  F -->|fail| H[Roll back to recorded deployment]Add these repository secrets: LAUNCH_DEPLOY_HOOK_URL, LAUNCH_TOKEN, LAUNCH_PROJECT_UID and LAUNCH_ENVIRONMENT_UID.

```yaml
name: Deploy to Launch

on:
  push:
    branches: [main]

concurrency:
  group: launch-production
  cancel-in-progress: false

env:
  LAUNCH_API: https://launch-api.contentstack.com
  SITE_URL: https://www.example.com

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

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci
      - run: npm test

      - name: Record the current live deployment
        id: before
        env:
          LAUNCH_TOKEN: ${{ secrets.LAUNCH_TOKEN }}
          BASE: ${{ env.LAUNCH_API }}/projects/${{ secrets.LAUNCH_PROJECT_UID }}/environments/${{ secrets.LAUNCH_ENVIRONMENT_UID }}
        run: |
          PREVIOUS=$(curl -sf "$BASE/deployments?limit=20" \
            -H "Authorization: Bearer $LAUNCH_TOKEN" \
            | jq -r '[.deployments[] | select(.status == "LIVE")][0].uid // empty')
          echo "previous=$PREVIOUS" >> "$GITHUB_OUTPUT"

      - name: Trigger the deployment
        run: curl -sf -X POST "${{ secrets.LAUNCH_DEPLOY_HOOK_URL }}?commit=$GITHUB_SHA"

      - name: Wait until the deployment is live
        env:
          LAUNCH_TOKEN: ${{ secrets.LAUNCH_TOKEN }}
          BASE: ${{ env.LAUNCH_API }}/projects/${{ secrets.LAUNCH_PROJECT_UID }}/environments/${{ secrets.LAUNCH_ENVIRONMENT_UID }}
        run: |
          for attempt in $(seq 1 80); do
            STATUS=$(curl -sf "$BASE/deployments?limit=20" \
              -H "Authorization: Bearer $LAUNCH_TOKEN" \
              | jq -r --arg sha "$GITHUB_SHA" \
                '[.deployments[] | select(.commitHash == $sha)] | max_by(.deploymentNumber) | .status // "PENDING"')
            echo "Attempt $attempt: $STATUS"
            case "$STATUS" in
              LIVE) exit 0 ;;
              FAILED|CANCELLED|SKIPPED) echo "Deployment ended as $STATUS"; exit 1 ;;
            esac
            sleep 15
          done
          echo "Timed out waiting for Launch"; exit 1

      - name: Smoke test
        id: smoke
        run: |
          curl -sf -o /dev/null "$SITE_URL/"
          curl -sf -o /dev/null "$SITE_URL/pricing"

      - name: Roll back on a failed smoke test
        if: failure() && steps.smoke.outcome == 'failure' && steps.before.outputs.previous != ''
        env:
          LAUNCH_TOKEN: ${{ secrets.LAUNCH_TOKEN }}
          BASE: ${{ env.LAUNCH_API }}/projects/${{ secrets.LAUNCH_PROJECT_UID }}/environments/${{ secrets.LAUNCH_ENVIRONMENT_UID }}
        run: |
          curl -sf -X POST "$BASE/deployments/rollback" \
            -H "Authorization: Bearer $LAUNCH_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"deployment\": \"${{ steps.before.outputs.previous }}\"}"
```

How the pieces fit:

- concurrency stops two production deploys from overlapping in your pipeline. Launch would skip the older one anyway, and then the first job would wait for a deployment that never goes live.


- The job records the live deployment before it deploys. Once the new one is live, that recorded deployment is ARCHIVED, which makes it a valid rollback target.


- The status check matches on commitHash and takes the highest deploymentNumber, so a retry of the same commit doesn't confuse it.


- The rollback step only runs when the smoke test failed, not when the deployment itself failed. A failed deployment never replaced the live site, so there is nothing to undo.



If your Launch token expires faster than a deployment takes, mint it in an earlier step of the job instead of storing it as a long-lived secret.

## Roll back on purpose

Launch concept: a rollback makes an archived deployment live again without rebuilding it. Users see the restored version within seconds, and the version you rolled back from is kept.

Only ARCHIVED deployments within your plan's retention window can be used. FAILED and CANCELLED deployments never qualify. Besides the API call above, you can roll back with Rollback Deployment on the Deployments screen, or with the CLI:

```bash
csdx launch:rollback --config ./.cs-launch.json --environment production \
  --deployment <deployment-uid> --reason "Smoke test failed on /pricing"
```

The --reason is saved to the audit log.

Auto deployments from commits, webhooks and automations keep running during a rollback. If a Contentstack webhook calls your deploy hook on every publish, the next publish redeploys the code you just rolled back from. Pause those triggers before you roll back, and fix forward from there.

## Keep environment variables in Launch

Launch environment variables belong to the environment, not to the pipeline. Set them in the environment settings or with the Update an Environment API call. They are applied when a deployment runs, so a changed variable needs a new deployment before it takes effect. Each environment allows 128 variables and 14 KB in total, or 4 KB in total when you use Cloud Functions.

Your CI secrets are a separate set: the deploy hook URL, the Launch token and the UIDs. Don't copy app secrets into the pipeline just to pass them to Launch.

## Where people get confused

The deploy hook returned 200, but nothing is live yet. The hook only queues the deployment. Always poll the status before you test the site.

A deployment shows SKIPPED. A newer deployment was queued for the same environment. This is expected when two merges land close together.

The CLI can't log in. Check the region with csdx config:get:region, then check whether the CI user signs in through SSO. Login-based authentication doesn't work for identity provider users.

Redeploying to publish content. It works, because every deployment purges the CDN cache, but it costs a full build per publish. Read [Revalidate, prime or redeploy?](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch) before you wire a webhook to a deploy hook.

## Key takeaways

- Turn off auto deploy on the production environment when CI owns releases.


- Trigger Git-based deployments with POST <deploy-hook-url>?commit=$GITHUB_SHA so Launch deploys the commit you tested.


- Install @contentstack/cli-launch with csdx plugins:install before any csdx launch command, and log in with a non-SSO CI user.


- Poll GET .../deployments until your commit is LIVE, and fail on FAILED, CANCELLED or SKIPPED.


- Record the live deployment UID before deploying, and roll back to it with POST .../deployments/rollback when the smoke test fails.



## Next steps

- Set up [caching and on-publish revalidation](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming) so content changes don't need a deployment.


- Forward server logs to your observability stack with a Log Target, as described in [Logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits).


- Read [The Launch API is a product builder, not just a deployment endpoint](/blog/the-launch-api-is-a-product-builder-not-just-a-deployment-endpoint) for more of what the API can do.





---

## Do this with AI

Install the launch-trigger-and-monitor-launch-deployments and dx-cli skills from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Launch Deploy Helper profile in MCP Profile Hub. Then ask your agent:

> List the last ten deployments of my production environment on Launch with commit and status, and draft a GitHub Actions step that waits for the deploy to finish and fails on errors.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Which is the simplest way to deploy to Launch from CI?

A deploy hook. It is a unique URL that starts a deployment when you POST to it, optionally with a commit query parameter for Git-based projects.

### Do the csdx launch commands ship with the Contentstack CLI?

No. Install the plugin with csdx plugins:install @contentstack/cli-launch before running any launch command, or the step fails with command not found.

### Can I trigger a Git-based deployment through the REST API with an app token?

No. Create a Deployment with a commitHash requires a user token. App tokens can create deployments from uploaded files and read deployment status.

### Does a rollback rebuild the site?

No. A rollback makes a previously live, now archived, deployment active again without a build, so it completes much faster than a new deployment.

### Why do I see skipped deployments?

When several deployments are triggered for one environment, Launch skips the queued ones in between and only the latest takes effect.


---

## Step 2: Edge functions, redirects and caching on Launch

- **Source:** https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching
- **Checkpoint:** Redirects, an edge function and cache revalidation run on your project.

- **Authors:** Tim Benniks
- **Published:** 2026-11-24T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:03.694Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** headless, api, next

---

> **Full guide available:** [View all 4 chapters in one document](https://developers.contentstack.com/guides/launch-edge-functions-redirects-and-caching/full.md)

Every request to a Launch site passes through a few layers before your framework sees it. Most of the hard production problems live in those layers: a redirect that loops, a page that stays stale after a publish, a personalized response that leaks to the wrong visitor, or an edge function that throws CFL-0001 and only tells you so in a log you didn't know existed.

This guide walks through those layers in the order Launch runs them. It assumes you have a site on Launch already. The examples use Next.js where a framework matters, but the platform features work the same for Nuxt, Astro, Angular or a static site.

## What you'll learn

- How to write redirects and rewrites in launch.json


- When an edge function is the right tool, and how to write one for geo, auth and A/B routing


- How the Launch CDN caches responses and how to refresh it on publish


- How to read edge and server logs, forward them with Log Targets, and stay inside platform limits



## How a request moves through Launch

Launch concept: Launch puts a CDN and an edge runtime in front of your origin. You configure the first part declaratively, the second part with JavaScript, and the cache with standard HTTP headers.

flowchart LR  A[Visitor] --> B[launch.json redirects and rewrites]  B --> C["Edge function (functions/[proxy].edge.js)"]  C --> D[CDN cache]  D -->|miss| E[Origin: SSR or Cloud Functions]  D -->|hit| AA few rules follow from that order:

- A matching redirect in launch.json wins. If you define the same redirect in launch.json and in your edge function, the launch.json one runs.


- Password protection also takes precedence over the edge function.


- The edge function runs before the cache, so it can change the URL that gets cached. That is what makes it useful for A/B routing and for stripping tracking parameters.


- A request that a rewrite or an edge function forwards to the origin does not invoke the edge function a second time.



If you are coming from Vercel or Netlify, think of launch.json as the redirects and headers section of vercel.json or netlify.toml, and the edge function as a single middleware that runs on every request.

## How the chapters fit together

Each chapter covers one layer and can be read on its own.

- [Routing with launch.json](/guides/launch-edge-functions-redirects-and-caching/routing-with-launch-json) covers redirects, rewrites, path patterns, header injection and the limits of the file.


- [Edge functions in practice](/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice) covers the handler, environment variables, geolocation headers, header-based access control and cookie-based A/B routing.


- [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming) covers Cache-Control, cache tags, the Revalidate CDN Cache API, revalidating on publish and warming the cache after a deployment.


- [Logs, debugging and limits](/guides/launch-edge-functions-redirects-and-caching/logs-debugging-and-limits) covers server logs, Log Targets, the numbers you need to remember and the mistakes that show up most often.



If you only need to pick between revalidating, priming and redeploying, read [Revalidate, prime or redeploy?](/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch) first. If you want to drive deployments from a pipeline, continue with [Deploy from CI with the Launch CLI, REST API and deploy hooks](/guides/deploy-from-ci-with-the-launch-cli-and-api).

## Key takeaways

- Put static and pattern-based redirects and rewrites in launch.json at the root of your repository.


- Reach for functions/[proxy].edge.js only when the routing decision depends on request data such as headers, cookies or location.


- Treat Cache-Control as the contract with the CDN, and refresh it with the Revalidate CDN Cache API instead of redeploying for every content change.


- Check Server Logs first when something breaks at the edge, and set up a Log Target before you need history older than 24 hours.





---

## Do this with AI

Install the launch-platform skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills). Then ask your agent:

> Read my launch.json and functions folder and explain, for a request to /blog/old-post, which redirect, rewrite or edge function runs first and which cache headers the response ends up with.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### In what order does Launch process a request?

Redirects and rewrites from launch.json run first, then your edge function, then the CDN cache, and finally your origin (SSR or Cloud Functions).

### Do I need an edge function for redirects?

No. Static and pattern-based redirects belong in launch.json. Use an edge function when the decision depends on headers, cookies, geolocation or the hostname.

### Does Launch support Next.js revalidatePath and revalidateTag?

Not with the App Router Data Cache. On Launch you control caching with Cache-Control headers and refresh the CDN with the Revalidate CDN Cache API, Automations or a redeploy.

### Where do I see console.log output from an edge function?

In the Server Logs of the environment in Launch, with the CLI using csdx launch:logs, or in your own tooling through a Log Target.


---

## Step 3: Revalidate, prime or redeploy? Picking the right cache lever on Launch

- **Source:** https://developers.contentstack.com/blog/revalidate-prime-or-redeploy-picking-the-right-cache-lever-on-launch
- **Checkpoint:** You can pick revalidation, priming or a redeploy for a given content change.

- **Authors:** Tim Benniks
- **Published:** 2026-12-01T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:48.995Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** headless, api

---

When content on a Launch site looks stale, most teams redeploy. It always works, so it becomes the habit. But a redeploy is the most expensive of the three cache levers Launch gives you, and for most content changes it's the wrong one.

The three levers are revalidating the CDN, priming the cache, and redeploying. They solve different problems. Once you see which problem each one solves, the choice is usually obvious.

## The short version

Lever

What it does

What it costs

Use it when

Redeploy

Builds the site and purges the whole environment's CDN cache

A full build, every time

Code changed, or your pages are pre-rendered at build time

Revalidate

Purges cached responses by path, cache tag or hostname

One API call against a daily quota

Content changed on a server-rendered site

Prime

Requests a list of paths as part of a deployment so they're cached before visitors arrive

Origin load for those paths on each deployment

Your most visited pages are slow on a cold cache

Priming is not an alternative to the other two. It is the step that makes a redeploy less painful.

## What a redeploy really does

A deployment on Launch builds your project and, when it goes live, purges the CDN cache for that environment. Every page is a cache miss until someone requests it again.

That is why a redeploy fixes every staleness problem. It also means you pay for a full build and a cold cache for a one-word typo fix in a blog post. On a small site with a fast build that's fine. On a site with thousands of pages and a ten-minute build, an editor who publishes twenty times a day turns your build pipeline into a queue. Launch helps a bit here: when several deployments are triggered for one environment, it skips the queued ones in between. You still wait for the latest.

You can trigger a redeploy from a deploy hook, from the CLI with csdx launch --redeploy-latest, or from the Launch API. If you drive this from a pipeline, [Deploy from CI with the Launch CLI, REST API and deploy hooks](/guides/deploy-from-ci-with-the-launch-cli-and-api) shows the whole setup.

## What revalidation really does

Revalidation drops cached entries without building anything. You call the Revalidate CDN Cache endpoint on the Launch API with exactly one of three inputs:

```json
{ "cachePath": { "path": "/blog/my-post", "isPrefix": false } }
```

```json
{ "cacheTags": ["prod-blog"] }
```

```json
{ "hostnames": ["www.example.com"] }
```

The next request for a purged page goes to your origin and gets cached again. Nothing else on the site is touched.

This only makes sense when your origin can render fresh content on request. For a server-rendered page with Cache-Control: public, max-age=0, s-maxage=86400, revalidation is ideal: the CDN holds the page for a day, and you purge it the moment an editor publishes. For a page that was pre-rendered at build time, purging the CDN just fetches the same stale HTML again. That page needs a build.

Two practical notes. Revalidation has a daily quota per organization, which you can check with GET /usage-analytics/revalidate-cdn-cache. And cache tags are the way to stay well under it, because one tag purge can clear hundreds of URLs. I prefix every tag with the environment, like prod-blog and staging-blog, so a purge meant for staging can't touch production pages that share a tag name.

You can wire revalidation to publishing with the Launch connector in Automations, or with a small webhook route in your app. Both are covered step by step in [Caching, revalidation and cache priming](/guides/launch-edge-functions-redirects-and-caching/caching-revalidation-and-cache-priming).

## What priming really does

Cache priming takes a list of paths from launch.json and requests them as part of each deployment:

```json
{
  "cache": {
    "cachePriming": {
      "urls": ["/", "/pricing", "/docs", "/blog"]
    }
  }
}
```

You also switch on Enable Cache Priming in the environment's cache settings. After that, your homepage and top landing pages are already in the CDN when the first visitor arrives after a release.

The limits are what make it a supporting act. Paths must be relative and listed one by one; wildcards and regex aren't supported. Routes that send no-store or no-cache are requested but never cached, so priming them does nothing. And it only runs on a deployment, so it doesn't help after a revalidation. If your list comes from content, generate launch.json at build time instead of maintaining it by hand.

## A decision flow

This is the order I go through when something on a Launch site needs to change:

flowchart TD  A[Something changed] --> B{Code or config?}  B -->|Yes| R[Redeploy]  B -->|No, content| C{Is the page pre-rendered at build time?}  C -->|Yes| R  C -->|No, server-rendered with s-maxage| D{How many pages are affected?}  D -->|One or a few known URLs| P[Revalidate by path]  D -->|A section or everything using a component| T[Revalidate by cache tag]  D -->|One of several domains| H[Revalidate by hostname]  R --> E{Are top pages slow on a cold cache?}  E -->|Yes| F[Add them to cache priming]  E -->|No| G[Done]Code changes always need a deployment. Content changes need a deployment only if the content is baked into the build. Everything else is a question of how wide the purge should be.

## How we do it on this site

developers.contentstack.com runs on Launch, and it takes the redeploy route on purpose. Content pages are pre-rendered at build time with generateStaticParams, and a publish triggers a rebuild. Pages are served from the CDN as static HTML, and the origin almost never does any rendering work during a visit.

That choice works because the build is fast enough to run on every publish. A news site or a large commerce catalog would make the opposite choice: render on the server with a long s-maxage, tag responses by content type, and revalidate on publish. Pick the lever whose cost matches how often the change happens. Rare publishes can afford a build. Frequent publishes can't.

## Mistakes I keep seeing

Redeploying on every publish for a large site. The webhook goes straight to a deploy hook, editors publish in bursts, and the queue never empties. Switch those pages to server rendering with s-maxage and revalidate instead.

Revalidating pre-rendered pages. The purge works, the CDN fetches the page again, and it's the same old HTML. If the content is in the build output, only a build updates it.

Priming routes that can't be cached. Check the Cache-Control of every path on your priming list. A no-store page on that list costs origin requests and gives nothing back.

Cacheable pages that read cookies. The Launch CDN caches by URL, not by cookie. If a page renders differently per visitor, send no-store or move the personal part to a client-side call. For A/B tests, rewrite each variant to its own URL in an edge function, as shown in [Edge functions in practice](/guides/launch-edge-functions-redirects-and-caching/edge-functions-in-practice).

A broken automation eating the quota. A flow that fires the same purge in a loop, or sends a tag that never resolves, still counts every call. Check your revalidation usage after you set up a new automation.

## Concluding

Redeploy when code changes or when content lives in the build. Revalidate when content changes on a server-rendered page, and prefer tags over long lists of paths. Prime the handful of pages that matter most, so a deploy doesn't hand your first visitors a cold cache.

Start by checking two things on your own site: whether your content pages are pre-rendered or server-rendered, and what Cache-Control they send. Those two answers decide which lever you need.



---

## Do this with AI

Install the launch-platform skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Launch Deploy Helper profile in MCP Profile Hub. Then ask your agent:

> Look at last week's deployments on my Launch project and tell me which redeploys only shipped content changes and could have been a cache revalidation instead.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Does redeploying on Launch clear the CDN cache?

Yes. Every deployment purges the CDN cache for that environment, which is why a redeploy always shows fresh content.

### Is cache priming a replacement for revalidation?

No. Priming warms a fixed list of paths as part of a deployment. It doesn't react to content changes, so you still need revalidation or a redeploy for those.

### When should I revalidate instead of redeploying?

When the change is content, not code, and your pages are server-rendered with an s-maxage. Revalidation purges only what changed, without a build.

### Can I prime the cache without deploying?

Not with the built-in feature. Cache priming runs as part of a deployment, for the paths you list in launch.json.

