Skip to main content

Weekly release workflow

Application repositories ship one tested release per week. Feature work is integrated on staging, exercised there, and promoted to production together. Urgent fixes between those releases use a hotfix-* branch cut from production.

Audience: Engineers working in platform or strapi-docker.

Outcome: A feature reaches staging without dragging other unreleased work along, and the weekly production pull request promotes a frozen staging commit.

Branches​

BranchLifetimeCut fromRole
productionLong-lived—What is deployed to production. Protected.
stagingLong-lived—Integration environment. Protected.
feature/<name>Short-livedproductionOne feature or fix for the next weekly release.
hotfix-<name>Short-livedproductionUrgent fix that cannot wait for the weekly release.

production pull requests accept only staging (the weekly release) or hotfix-* (a patch). That check runs in platform and strapi-docker (.github/workflows/production-source.yml). A feature branch opened directly against production fails CI.

Normal release​

The normal release is the weekly promotion of staging into production. A patch uses the same production branch; it is smaller and happens between weeklies.

1. Branch from production​

git fetch origin
git checkout production
git pull origin production
git checkout -b feature/<name>

The feature branch contains only your change against what is live. Keep the branch until the weekly release if you may still need to drop the feature.

2. Integrate on staging​

Open a pull request from feature/<name> into staging. Staging deploys from staging. QA and further review happen on that environment.

Further commits for the same feature go on the feature branch and merge to staging again.

3. Freeze, then promote​

Before opening the weekly pull request, freeze staging. After the freeze, merge only fixes that block the release. New features wait until production has been merged back into staging.

Open one pull request from staging into production for the frozen commit. That pull request is the release: CI already passed on the feature pull requests, and this check confirms the source branch is staging.

To hold a feature back, revert it on staging or leave it unmerged before the freeze. Promote the staging tip that remains.

4. Sync staging​

Immediately after the production merge, merge production back into staging. The next feature branches start from what shipped. Commits that landed on staging after the freeze stay only on staging.

Patch release​

A patch is a production fix that cannot wait for the weekly train.

1. Branch from production​

git fetch origin
git checkout production
git pull origin production
git checkout -b hotfix-<name>

The name must match hotfix-*. Any other prefix is rejected by the production source check.

2. Merge to production​

Open a pull request from hotfix-<name> into production, deploy, and treat that merge as the patch release.

3. Sync staging​

Merge the same hotfix-<name> branch into staging, or merge production into staging immediately after the patch. Staging has to contain the fix before the next weekly release, or that release will conflict with it or drop it.

Rules of thumb​

Do​

  • Cut feature/* and hotfix-* from current production.
  • Merge features into staging and let them sit there until the weekly promotion.
  • Freeze staging before the release pull request.
  • Merge production back into staging after every production merge, weekly or patch.
  • Revert or withhold a feature on staging when it should miss the release.

Avoid​

  • Cutting feature branches from staging. They inherit other unreleased work and become hard to revert.
  • Opening a feature pull request against production. CI allows only staging and hotfix-*.
  • Continuing to merge features into staging after the freeze. The commit you tested will not be the commit you ship.
  • Cherry-picking individual commits from staging onto production. That duplicates history and makes the next merge worse.
  • Fixing production only on staging, or only on production. A patch has to land on both.

Review checklist​

  • Feature branch was created from production
  • Pull request target is staging for feature work, production only for staging or hotfix-*
  • Hotfix branch name matches hotfix-*
  • Staging was frozen before the weekly staging → production pull request
  • production was merged back into staging after the release or patch