---
title: "How releases work"
description: "Why a released service stays built where its source lives, what an install copies and what stays private, the release lifecycle, how to move code to a new owner without an outage, and the easy mistakes."
url: "https://docs.alisx.com/explanation/releases/"
---
# How releases work

A release lets a service built in one product run in another, possibly in another build environment, without handing over its source. This page explains the line between releasing and installing, what crosses it and what stays private, how a release reaches the products that installed it, the order that moves a service's code to a new owner safely, and the mistakes that are easy to make. For the commands, see `alis service release`, `alis service install` and `alis service unrelease` in [alis service](https://docs.alisx.com/reference/cli/service.md).

## Release the build, keep the source

Two acts, on two sides:

- **Release**, at the source. The source product makes a built version of its service available to the build environments it names. A release also declares the environment variables every installer has to set: their names, a description and whether each is required. Releasing again sends a newer version to every product that already installed the service.
- **Install**, at the destination. A product installs the released service as a **managed copy** under a package id of its own. The copy records which source it follows and receives the source's deployable artifacts. It is a service the destination can run, not a copy of the source's code to edit.

The source keeps owning and building the service. The destination runs it.

## What crosses the boundary

| Question | Answer |
|---|---|
| Can the installing product see the source code? | No. Neither release nor install copies a repository or a working tree, and installing grants no access to the source's repositories. |
| What is copied to the destination? | What it takes to configure and run the released version: the built container images, the deployment configuration, the service's descriptors and its generated packages. |
| Where does the installed service run? | In the destination. It sets its own variable values and deploys into its own deployment environments, so the Cloud Run service and everything around it live in the destination's Google Cloud project. |
| Who makes future versions? | The source. Each later release becomes a new version of every managed copy. |
| What about the source's variable values? | They stay with the source. A release carries variable names, descriptions and whether they are required, never values or secrets. |

This split is the point. The owner of the code keeps it private and keeps one place to fix it; each product that depends on the service gets a deployment it controls, in its own project, with its own configuration and its own production gate.

## From source to destination

```mermaid
flowchart TB
  B[Build at the source] --> R[Release to named build environments]
  R --> I[Install as a managed copy]
  I --> C[Set the declared variables]
  C --> D[Deploy in the destination]
  B -.->|later builds| R
  R -.->|new version on every copy| D
```

1. **Define and build at the source.** The contract and the code are maintained in the source product, and a successful build produces the version that can be released.
2. **Release to an audience.** The first release has to say who may install: named build environments, or any. Later releases keep that audience unless you change it. The latest build is released unless you name a version.
3. **Install in the destination.** The destination creates its managed copy, which receives the source's latest release straight away as its first version.
4. **Configure and deploy there.** The destination sets the variables the release declared, in each deployment environment, and deploys the copy's version as it would any other.
5. **Release updates from the source.** A later release builds a new version on each copy, numbered in that copy's own sequence, and waits until every copy has it or names the ones that failed. Each destination then deploys it, by hand or automatically into the deployment environments it chose to have updated on a new release.

## Moving code to a new owner without an outage

Sometimes a service already runs in one product and its code should belong to another: a team that should own it, or a product that protects it better. Releases make that move possible without taking the running service down, as long as the order is right. The rule is that the old service stays until the new path has been proven.

1. **Copy the code to its permanent owner.** Put the implementation in the product that should own it, and leave the old service running.
2. **Define and build it there.** Get a releasable version in the new home before anything depends on it.
3. **Release it to the build environment where the service has to run**, declaring the variables that product will need.
4. **Install and validate alongside the old service.** If the old service still holds the package id you want, install under a temporary id or plan a short window for the swap. Set the variables and deploy.
5. **Remove the old service last.** Move callers and routes to the managed copy, check it end to end, and only then remove the old deployment and the old code.

Done in another order, each step can leave the destination with nothing running, or with a service nobody can update.

## Easy mistakes

**Treating an install as a fork.** The destination has a managed copy, not a repository, so there is nothing there to edit or build on its own. Make the change at the source, build it there, and release a new version.

**Deleting the source first.** Copies keep the artifacts they have already received, but every new release and every future install comes from the source. Keep it for as long as any destination needs updates.

**Expecting unrelease to recall.** Unreleasing sets the source back to an ordinary service and clears its release records. Copies already handed out stay where they are; they simply get no further releases. Retire a released service by agreeing it with each destination, not by unreleasing it.

**Expecting variable values to travel.** Only the names, descriptions and whether each is required go with a release. Set the actual values, secrets included, in every destination's deployment environments.

**Leaving the audience empty.** On the TUI's Release page an empty list of build environments means any build environment may install, not none. The CLI makes the choice explicit: `--organisation` (repeatable) or `--any-organisation`. Name the build environments when a release is meant for one customer or partner.

## Related

- [alis service](https://docs.alisx.com/reference/cli/service.md)
- [Resource model](https://docs.alisx.com/reference/environments/resource-model.md)
- [Deployment environments and versions](https://docs.alisx.com/explanation/environments-and-versions.md)
- [Organisations, products and services](https://docs.alisx.com/explanation/organisations-products-services.md)
- [Deploy a version](https://docs.alisx.com/how-to/alis-build/deploy-a-version.md)