Releases

A release is an immutable, built version of your stack that Alien rolls out to your deployments. One command, run from the project folder, builds and ships it:

alien release

A channel points at one release, and each deployment follows a channel. Moving a channel rolls its release out to every deployment that follows it, with no action from the customer's admin.

1. 1

   Releaseyou or CI

   alien release builds the stack, pushes images, and records the release.

2. 2

   ChannelAlien

   The release becomes the target of a channel, production by default.

3. 3

   Deploymentseach environment

   Every deployment following the channel updates to it: through cloud APIs (push) or by pulling over outbound HTTPS (pull).

Create a releaseCopy Anchor Link

alien release builds every platform the stack supports, pushes the images, creates the release, and advances the production channel. Useful flags:

A release must cover every platform the channel's deployments run on. Releasing --platforms aws to a channel with a Google Cloud deployment fails with RELEASE_CHANNEL_INCOMPATIBLE, which names each missing platform and its deployment count. Promoting such a release fails the same way.

• --channel and --no-promote can't be combined.
• Every project starts with a production channel.
• Unchanged build outputs are reused, and images already pushed by an earlier release aren't pushed again.

To create a release now and ship it later, for example an urgent fix you want to review first:

alien release --no-promote --title "Fix checkout"
alien releases promote <release-id> --channel production

The first command prints the release ID. The release page in the dashboard also has Promote this exact release.

Promotion schedules every eligible deployment on that channel to update. alien releases promote moves the channel only if nobody promoted another release in between; otherwise it fails, so you can check and retry.

To build once in CI and release from a later job:

1. Save the .alien folder that alien build --platforms aws,gcp writes as a CI artifact.
2. Run alien release --prebuilt in the release job.

It reuses the saved stack and build outputs, so the release job needs no application dependencies. It still pushes local images; images already stored as remote URIs are reused.

Published is not deployedCopy Anchor Link

Creating a release changes nothing by itself. A deployment moves to it only when it follows a channel that points at it. A deployment stays on its current release when:

• it follows a different channel, or is pinned to a release
• its update policy requires approval
• the release needs initial setup again and the customer's admin hasn't run it
• it is air-gapped and waits for the next sync

Check where a release runs with alien releases get <release-id>, which shows rollout progress per deployment. The dashboard's Releases page shows the same view.

ChannelsCopy Anchor Link

A channel is a pointer, not a copy. Use a second channel to test a release on a few deployments before production:

alien releases create-channel staging
alien deployments set-channel <deployment-id> staging

Then release to staging, test, and promote the exact same release to production. A plain alien release advances only production, so it never overwrites what staging is testing. Promotion reuses the built artifacts; nothing is rebuilt:

alien release --channel staging
alien releases promote <release-id> --channel production

List channels with alien releases channels, and releases no channel points at with alien releases ls --all-channels.

Pin and roll backCopy Anchor Link

Pin one deployment to a known release, for example while you debug a regression for one customer:

alien deployments pin <deployment-id> <release-id>

In the dashboard, open the release under Releases and use Pin to this release on the deployment's rollout row. The deployment page has Pin release, and Unpin for a pinned deployment.

A pinned deployment ignores its channel. Run alien deployments pin <deployment-id> with no release to unpin it. Changing a pinned deployment's channel sets where it resumes once unpinned.

To roll back everyone, promote the earlier release to the channel again. Or roll forward: fix the problem and release again, and deployments converge to the new release.

Release from CICopy Anchor Link

Release to staging on every merge, and promote to production by hand. Create an API key and store it as the ALIEN_API_KEY secret:

alien api-keys create --for deployments --description github-actions

The secret is printed once. In the dashboard, project keys are under Settings → API Keys.

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      ALIEN_API_KEY: ${{ secrets.ALIEN_API_KEY }}
      ALIEN_WORKSPACE: acme
      ALIEN_PROJECT: acme-docs
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: curl -fsSL https://alien.dev/install | INSTALL_DIR="$HOME/.local/bin" sh
      - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: npm ci
      - run: alien release --channel staging --title "${{ github.sha }}" --json > release.json
      - run: echo "Released $(jq -r .releaseId release.json)"

A second workflow, started by hand with the release ID, runs alien releases promote <release-id> --channel production with the same environment. Promoting through a reviewed workflow gives you an audit trail of who shipped what.

Releases for software Alien didn't shipCopy Anchor Link

Remote Operator can run inside a product you already ship with your own Helm chart or ECS task. Alien didn't build that software, but you can still record which version runs where:

alien release --no-stack --version 1.4.0

This records version 1.4.0 without building or pushing anything. The Remote Operator container reports the version each environment runs, so the dashboard shows versions and rollout across those environments.

NextCopy Anchor Link

• Roll out releases: staged rollouts across many customers
• Follow a deployment: watch a customer's initial setup and the rollouts after it
• CLI reference