Prepare and submit a release
Create a release, choose its package versions, attach an SBOM, rehearse the upgrade on a restored copy and submit it for review.
Before you begin
- The target environment exists, is approved and is not archived: Set up environments and release policies.
- The package versions you want are Reviewed or Certified: Register, review and certify packages.
- A stored backup exists, so the upgrade can be rehearsed on a restored copy.
Steps
- Open Platform > Releases > Releases and press New.
- Enter the Title.
- Choose the Environment. If you leave Release policy empty and exactly one active policy fits that environment's tier, it is attached automatically.
- Check the Migration head. It defaults to this build's database migration head. It is required to submit.
- Write the Rollback plan (forward fix or restore, and how). It is required to submit.
- Press Save. The release gets the next number, for example
REL-0001, and is a Draft. - Open the Packages tab, press Edit, tick the package versions (1 to 200, one version per code) and press Save packages. Only reviewed or certified versions are offered.
- Open the Evidence tab and press Take and attach an SBOM. This is only possible while the release is a draft.
- Choose a backup (or leave Newest backup) and press Rehearse the upgrade on a restored copy.
- Open Platform > Operations > Job runs and press Run the scheduler now so the rehearsal runs.
- Open the Gates tab and read Before submit.
- Press Submit.
What the submit gate checks
The gate checks that every package's licence is approved, that the files of each package still match their recorded digest, that dependencies and the core range are satisfied, that no unwaived high or critical vulnerability is in the SBOM, and, if the policy lists them, that an SBOM is attached.
When everything passes the release becomes Reviewed. The artifact hash and provenance (commit, clean tree, host, time) are written and every gate is recorded with its time.
If a check fails the release stays a Draft but the failing gates are saved on the Gates tab, so you can see what to fix. Examples of refusals:
| Message | Fix |
|---|---|
| 'Write the rollback plan: forward fix or restore, and how.' | Fill the rollback plan. |
| 'Say which migration head the release brings the schema to.' | Fill the migration head. |
| 'Every package's licence is approved: Licence review open for X_DEMO 1.0.0 (pending)' | Ask an approver to complete the licence review. |
| 'Package artifacts match their recorded digest: X 1.0.0: the files no longer match the reviewed digest.' | A package has drifted. Register a new version or restore the files. |
| 'No unwaived high or critical advisory: No SBOM: nothing to check vulnerabilities against.' | Take and attach an SBOM. |
| '... 1 unwaived high or critical advisory(ies) in the SBOM.' | Update the component, or have an approver waive the advisory. |
Stage
A release manager opens the Reviewed release and presses Stage. The gate requires a passed rehearsal of this release in the last 30 days that reached the release's migration head. If the policy lists them it also needs a passed restore drill and module contract checks.
- Without a rehearsal: 'Upgrade rehearsal passed on a copy: No passed upgrade rehearsal for this release in the last 30 days.'
- Wrong head: 'Rehearsal DRL-00002 reached <x>, not <y>.'
- Policy asks for a restore drill and none passed: 'No passed restore drill in the last 30 days.'
The release becomes Staged, ready for approval: Approve and activate a release.
Good to know
- Only a draft release can be edited: 'Only a draft release changes. Reject it back to draft first.'
- Rehearsals on PostgreSQL need the database role to be allowed to create a scratch database. Without it the rehearsal fails with 'Could not create the scratch database for the drill (...). The database role needs CREATEDB.' and no release can be staged until that is fixed.
- Pressing Submit twice with the same idempotency key through the API returns the first answer instead of doing it twice.