Deploy release (CI promote on app deploy)

Promote published staging translations to production and rebuild production CDN bundles from your app’s production deploy pipeline.

Decision: D-056 · Admin fallback: Environment release

---

When to use

Path	Who	When
Deploy-release (this guide)	CI after app prod deploy	You want production copy to update when the binary ships
Admin Promote & publish	Owner/admin	No CI wiring yet, or emergency manual release

Staging overlay and staging publish stay the day-to-day edit path. Deploy-release does not auto-run on every staging publish.

---

Prerequisites

1. Paid plan that can publish production (Free is blocked).
2. In admin → Projects → select the application → Deploy release (CI):
   • Enable CI deploy-release
   • Create a deploy token (dpt_…) — copy once into CI secrets as STRINGPUSH_DEPLOY_TOKEN
3. Staging values you want live must already be published on staging (approvals still apply when enabled).

---

CLI

export STRINGPUSH_DEPLOY_TOKEN=dpt_…
export STRINGPUSH_API_BASE_URL=https://api.platform.stringpush.com

npx -y @stringpush/cli@0.8.0 deploy-release \
  --project <project-uuid> \
  --application <application-uuid> \
  --release-ref "$GITHUB_SHA"

The CLI sends an Idempotency-Key (generated UUID unless you pass --idempotency-key). Completed responses replay for 24 hours. In-flight claims use a renewing lease (heartbeat about every minute). If ownership is lost before the next mutating step, the request fails with 409 before publish. After publish, success requires writing the idempotency cache (complete); otherwise the API returns 409 or another holder’s replay — never 200 with a pending claim.

HTTP 200 means promote finished and production CDN bundles were built in-process (deploy-release does not return success while publish is only queued).

---

GitHub Actions example

# After your production app deploy job succeeds:
deploy-release:
  needs: deploy-production
  runs-on: ubuntu-latest
  steps:
    - name: Promote staging translations to production
      env:
        STRINGPUSH_DEPLOY_TOKEN: ${{ secrets.STRINGPUSH_DEPLOY_TOKEN }}
        STRINGPUSH_API_BASE_URL: https://api.platform.stringpush.com
      run: |
        npx -y @stringpush/cli@0.8.0 deploy-release \
          --project "${{ vars.STRINGPUSH_PROJECT_ID }}" \
          --application "${{ vars.STRINGPUSH_APPLICATION_ID }}" \
          --release-ref "${{ github.sha }}" \
          --idempotency-key "gha-${{ github.run_id }}-${{ github.run_attempt }}"

---

GitLab CI example

deploy_release:
  stage: deploy
  needs: ["deploy_production"]
  script:
    - |
      npx -y @stringpush/cli@0.8.0 deploy-release \
        --project "$STRINGPUSH_PROJECT_ID" \
        --application "$STRINGPUSH_APPLICATION_ID" \
        --release-ref "$CI_COMMIT_SHA" \
        --idempotency-key "gl-$CI_PIPELINE_ID-$CI_JOB_ID"
  variables:
    STRINGPUSH_API_BASE_URL: "https://api.platform.stringpush.com"

Store STRINGPUSH_DEPLOY_TOKEN as a masked CI variable.

---

API (advanced)

POST /v1/projects/{projectId}/applications/{applicationId}/deploy-release
Authorization: Bearer dpt_…
Idempotency-Key: <unique-per-deploy>
Content-Type: application/json

{ "releaseRef": "abc123" }

Response includes promote counts, production environment id, and per-locale bundle versions. Success means bundles are already written — not merely enqueued.

---

Troubleshooting

Symptom	Check
403 deploy promote disabled	Enable CI deploy-release on the application
401 invalid token	Use a current dpt_… deploy token (not runtime trt_ or sync stp_)
400 missing Idempotency-Key	Required for deploy-token callers
402 plan limit	Free plan cannot publish production
503 publish unavailable	Transient; retry the same Idempotency-Key
No string change	Ensure staging values are published, then re-run deploy-release

Docs site: keep this page linked from Environment release Scenario B.