Skip to main content
Contentstack MCP profile hub is in general availability!

Deploy from CI with the Launch CLI, REST API and deploy hooks

•
10 min read

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.

curl -X POST "$LAUNCH_DEPLOY_HOOK_URL?commit=$GITHUB_SHA"
{ "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.

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:

{
  "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:

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 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

DiagramMermaid

Add these repository secrets: LAUNCH_DEPLOY_HOOK_URL, LAUNCH_TOKEN, LAUNCH_PROJECT_UID and LAUNCH_ENVIRONMENT_UID.

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:

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? 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

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.