Promotion

Promotion moves a proven image from one environment to another. No rebuild, no uncertainty. The exact image that passed your staging tests is the exact image that runs in production. Byte for byte.

Promote a service

Specify where the image is coming from and where it's going:

mutation {
  promote(input: {
    projectId: "myapp"
    service: "api"
    fromEnvironment: "staging"
    toEnvironment: "production"
  }) {
    name
    environment
    imageTag
  }
}

Lucity copies the image tag from the source environment to the target environment and triggers an ArgoCD sync. That's it. No build queue, no waiting for source code to compile, no crossing your fingers that the same code produces the same image.

Know why promotion matters

Rebuilding for each environment is a gamble most people don't realize they're taking. The same source code can produce subtly different images due to:

• Dependency resolution: npm install might pull a newer patch version. Go modules might resolve differently with a warmer cache.
• Build timing: a flaky network during the build can cause a different dependency mirror to be used.
• Non-deterministic toolchains: some build tools embed timestamps or randomized identifiers.

These differences are usually harmless. Until they're not, and you spend a Thursday night figuring out why production broke when staging was fine.

Promotion sidesteps all of this. One build, multiple environments, zero surprises.

Understand how it works under the hood

Promotion is a Git operation, not a build operation. Here's what happens:

1. The packager reads the image tag from environments/<source>/values.yaml.
2. It writes that same tag to environments/<target>/values.yaml.
3. It commits with a semantic message: promote(production): api a1b2c3d from staging.
4. The deployer syncs the ArgoCD Application for the target environment.
5. ArgoCD detects the new commit and rolls out the change.

No containers are built. No source code is cloned. The registry already has the image. You're just telling Kubernetes to use it in a different namespace.

Follow the typical promotion flow

The well-trodden path:

development → staging → production

1. Build in development: push code, trigger a build, verify it works.
2. Promote to staging: the same image runs against staging data and config. Run your integration tests, do your QA.
3. Promote to production: confidence earned, not assumed. Ship it.

Each promotion is a lightweight Git commit and an ArgoCD sync. The whole flow from staging to production takes seconds, not minutes.

You can also promote between any two environments. There's no enforced pipeline order. Need to promote from a PR preview directly to staging for a quick demo? Go for it.