# Releases & Promotions

Source: https://www.jawsdeploy.net/features/releases-promotions

A release is an immutable snapshot - packages, variables, deployment process, everything. Promotion is the act of running that same snapshot somewhere new. No rebuilds, no drift.

## What's actually in a release

When you create a release in Jaws Deploy, the platform takes a **snapshot** of three things and freezes them together under a SemVer 2.0 version number:

## Three frozen pieces

- **Packages**: The exact package versions selected at release time - .zip, .tar, .nupkg, whatever your steps consume.
- **Variables**: Variable definitions as of release creation. Values still resolve per environment, but the variable *set* is frozen.
- **Deployment process**: The ordered steps that were in the project at the time. Edits to the project later do not retroactively change old releases.

> **// The single most useful invariant - Promotion does not rebuild. Ever.**
> 
> When you promote release 2026.5.16 from Staging to Production, Jaws Deploy runs the *same* release: same packages, same step definitions, same variable schema. The only thing that changes is which environment-scoped values get resolved. That is what makes a Staging signoff actually mean something.

## SemVer 2.0, but with intent

Releases are versioned using SemVer 2.0 - so `1.4.2`, `2.0.0-rc.1`, `2026.5.16+build.4218` all work. The platform doesn't *force* a versioning scheme on you, but the convention that earns its keep is **CI-generated version, deploy-time confirmation**. Your build job decides the version. Jaws Deploy takes it and promotes it. Humans don't type version strings.

## How a CI job typically creates a release

Most teams call this from TeamCity, GitHub Actions, or a Jenkinsfile right after a successful build:

```
Connect-JawsDeploy `
    -Url "https://app.jawsdeploy.net" `
    -ApiKey $env:JAWS_API_KEY

New-JawsDeployRelease `
    -Workspace   "default" `
    -Project     "checkout-service" `
    -Version     "2026.5.16.${env:BUILD_NUMBER}" `
    -Packages    @{ "Checkout.Web" = "2026.5.16" } `
    -ReleaseNotes (Get-Content .\CHANGELOG.md -Raw)
```

## Lifecycles: the path a release has to walk

A **Lifecycle** defines the ordered phases a release must pass through. The default is the obvious one - Dev -> Staging -> Production - but lifecycles are flexible enough to model things like "smoke environment then a manual approval then prod" or "two canary regions in parallel before global rollout".

Lifecycles attach to projects via **channels**. A channel says: "hotfix releases go through this shorter lifecycle that skips Dev." A normal release goes through the standard one. Same project, two paths.

**Dev -> Staging -> Production**

Every phase must succeed before the next is allowed. Reasonable safety net for the 95% case.

**Staging -> Production**

Skip Dev when the situation demands it. The lifecycle records that you skipped, so audit is preserved.

> **// Why this beats "just redeploy from CI" - Rebuilds are the enemy of repeatability.**
> 
> If you ship to Staging by running the build, and then ship to Production the next day by running the build *again*, you have shipped two different artifacts. Source might be identical. Dependencies, base images, transient toolchain bits - those drift in hours. A real release captures the artifact once and stops asking CI to reproduce it.

## Promotions in practice

Once a release exists, promoting it is a verb. From the UI, the REST API, or the PowerShell SDK, you tell Jaws Deploy "deploy release X to environment Y". The platform validates the lifecycle ("is this environment the next allowed phase?"), resolves variables for that environment, runs the steps, and records the deployment.

A single release can be deployed many times to the same environment - useful for re-runs after a fix, for canary rollbacks, or for that one customer who needs the same artifact deployed to a fresh tenant box.

## And what it does not

- **Guarantees** the same packages, same steps, same variable schema as the original release.
- **Guarantees** the lifecycle is respected unless you explicitly bypass it with a channel.
- **Does not** guarantee environment state. If Staging and Production disagree about, say, the OS patch level, that is on you to detect.
- **Does not** snapshot live external systems (databases, third-party APIs). Those drift independently.

## The mental model that makes evaluators relax

Think of a release as a **plan you can re-execute**. The plan is fixed; the destination changes. That single property - the plan is fixed - is what lets a team say "this release went through Staging" and have it actually mean something to the auditor reading it six months later.