intropy deploy

Authoritative reference for intropy deploy: moving components between environments.

Everything here goes through the GitOps repository and ArgoCD, never kubectl: pin and promote write commits to environment overlays, diff and status report, and sync asks ArgoCD to apply a committed change. Publishing the release manifests these commands can deploy from is intropy release; creating the overlay files in the first place is intropy manifests create. The deployment model and workflow are described on the intropy.run Deploy pages.

The surface

intropy deploy pin <component> [version] [flags]
intropy deploy promote <component> [flags]
intropy deploy diff <component> [flags]
intropy deploy status <component> [flags]
intropy deploy sync <component> [flags]

The component is located by searching the GitOps repository for domains/*/*/<component>; if the name is ambiguous, the error lists the candidates and --domain/--system disambiguate.

deploy.yaml

A deploy.yaml at the GitOps repository’s root marks it as deployable. It declares the registry, the ArgoCD server, and the environment graph:

schemaVersion: 1
registry: harbor.intropy.io
argocd:
  server: argocd.intropy.io
  appNamespace: customer-acme
environments:
  dev: { sync: auto }
  staging: { sync: auto, promotesFrom: [dev] }
  prod: { sync: manual, promotesFrom: [staging], requireSourceHealthy: true }

In brief: sync: auto environments are reconciled by ArgoCD as soon as a commit lands, while sync: manual environments record intent and wait for deploy sync. promotesFrom is the promotion graph that deploy promote enforces, and requireSourceHealthy additionally requires the source environment to be Synced and Healthy at the pinned revision. The semantics of the graph, and how to design one, are on the Deploy pages.

ArgoCD connection

Credentials come from the argocd CLI’s own configuration, so after argocd login no extra setup is needed. ARGOCD_SERVER and ARGOCD_AUTH_TOKEN override it: those are argocd’s variable names, honoured deliberately so an existing CI setup works unchanged. Server precedence is --argocd-server, then ARGOCD_SERVER, then deploy.yaml, then argocdServer in the user configuration.

intropy deploy pin

Pin the image digests for a component into one environment’s kustomize overlay.

Without a version, the commit comes from HEAD in the current source repository, which must be clean under the component’s source paths and pushed (CI builds pushed commits, so an unpushed one has no image). If CI has not published the digests yet the command fails, unless --watch polls the registry until they appear. With a version, the digests come from that release’s manifest instead: no source repository is read, and the command works from any directory.

intropy deploy pin order-extractor --env dev --plan
intropy deploy pin order-extractor 1.4.2 --env staging

Flag	Description
-e, --env <environment>	Target environment. Required.
--plan	Render and diff the change without writing to git.
-w, --watch	Wait for the commit’s images to appear in the registry instead of failing immediately.
--allow-dirty	Deploy despite uncommitted changes under the component’s source paths.
--no-wait	Push without waiting for ArgoCD to sync.
--timeout <duration>	How long to wait for ArgoCD to converge. Default 5m0s.
--domain <name>, --system <name>	Disambiguate the component.
--argocd-server <addr>	ArgoCD server address (see ArgoCD connection).
--gitops-repo <url>	GitOps repository URL. Defaults to gitopsRepo from configuration, or INTROPY_GITOPS_REPO.
-o, --output <format>	plain (default) or json. Progress goes to stderr and the diff to stdout, so --plan is pipeable.

When the target environment declares promotesFrom, the plan also reports whether those digests are what the upstream environment is already running. After pushing, the command waits for ArgoCD to apply the new revision; --no-wait skips that, and environments that sync manually never wait: they record intent and print the deploy diff/deploy sync follow-up. Re-running once a digest is already pinned prints already at … and exits 0 without creating an empty commit.

intropy deploy promote

Copy the image digests a component has pinned in one environment into another environment’s overlay.

Promotion resolves nothing. It does not look a version up in the registry and does not read a source repository: it reads the digests --from currently pins and writes those exact values, which is what makes “production runs the bytes staging tested” a fact rather than a hope.

intropy deploy promote order-extractor --from staging --to prod

Flag	Description
--from <environment>	Environment to copy the pinned digests from. Required.
--to <environment>	Environment to write them into. Required.
--plan	Render and diff the change without writing to git.
--no-wait	Push without waiting for ArgoCD to sync.
--timeout <duration>	How long to wait for ArgoCD to converge. Default 5m0s.
--domain <name>, --system <name>	Disambiguate the component.
--argocd-server <addr>	ArgoCD server address (see ArgoCD connection).
--gitops-repo <url>	GitOps repository URL. Defaults to gitopsRepo from configuration, or INTROPY_GITOPS_REPO.
-o, --output <format>	plain (default) or json.

Two deploy.yaml policies are enforced here (a pin only reports on them), and both refuse before anything is written. The target’s promotesFrom must permit the edge, so dev → prod is refused when prod promotes from staging. And where the target sets requireSourceHealthy, the source’s ArgoCD application must be Synced and Healthy at the revision its current digests were pinned by (a healthy application at some later revision does not show that these bits ran). Environments that sync manually record the intent, stop, and print the sync command to run.

intropy deploy diff

Render an environment’s manifests at the revision ArgoCD has applied and at the revision deploy sync would apply next, and print the difference.

This is the review half of an environment with sync: manual: it answers “what changes in the cluster if I sync this” with the resources themselves rather than a one-line image pin. It is not --plan, which diffs an uncommitted edit for the person writing the change. Here both sides are commits, so everything between them counts, including a base that moved and deployments that stacked up unapplied.

intropy deploy diff order-extractor --env prod

Flag	Description
-e, --env <environment>	Target environment. Required.
--domain <name>, --system <name>	Disambiguate the component.
--argocd-server <addr>	ArgoCD server address (see ArgoCD connection).
--gitops-repo <url>	GitOps repository URL. Defaults to gitopsRepo from configuration, or INTROPY_GITOPS_REPO.
-o, --output <format>	plain (default) or json. The diff travels inside the JSON as .diff, so -o json disables colour.

ArgoCD does the rendering, because the Application is the whole input: overrides it carries are invisible to a local kustomize build, and a diff that is not what gets applied is worse than no diff. ArgoCD must therefore be reachable. A non-empty diff still exits 0: this reports, it does not gate. Nothing is written to git.

intropy deploy status

Report the release, image digest, age, sync state and health of a component in every environment it is onboarded to, one row each, with a line under the table saying whether they agree.

intropy deploy status order-extractor

Flag	Description
--domain <name>, --system <name>	Disambiguate the component.
--argocd-server <addr>	ArgoCD server address (see ArgoCD connection).
--gitops-repo <url>	GitOps repository URL. Defaults to gitopsRepo from configuration, or INTROPY_GITOPS_REPO.
-o, --output <format>	plain (default) or json.

Release, digest and age come from the environment’s overlay in the GitOps repository, dated by the commit that last changed it. Sync and health come from ArgoCD; if ArgoCD cannot be reached those two columns are left empty and everything else still prints. An environment whose overlay cannot be read, or that pins a tag rather than a digest, is reported under the table rather than treated as an error. Rows follow the promotion graph in deploy.yaml, last row furthest downstream.

Nothing is written to git, no sync is triggered, and the exit code is 0 even when environments disagree. To gate in CI, read consistent from --output json, which also carries every image and the deploy time as an instant.

intropy deploy sync

Apply the GitOps change already committed for one environment, by asking ArgoCD to sync its application.

This is the other half of an environment with sync: manual. A deploy or a promotion into such an environment records intent by pushing a commit and stops; nothing reaches the cluster until someone with the rights to apply it runs this. The authorisation and the audit trail live in ArgoCD, which evaluates the caller through its own RBAC.

intropy deploy sync order-extractor --env prod --revision 7c30d81

Flag	Description
-e, --env <environment>	Target environment. Required.
--revision <commit>	The commit whose diff you reviewed; the sync is refused if the pending change is a different one.
--no-wait	Return once the sync is accepted, without waiting for it to converge.
--timeout <duration>	How long to wait for ArgoCD to converge. Default 5m0s.
--domain <name>, --system <name>	Disambiguate the component.
--argocd-server <addr>	ArgoCD server address (see ArgoCD connection).
--gitops-repo <url>	GitOps repository URL. Defaults to gitopsRepo from configuration, or INTROPY_GITOPS_REPO.
-o, --output <format>	plain (default) or json.

The revision synced is the commit that last changed the environment’s overlay, not the branch head. Pass --revision to name the commit you actually reviewed: if the pending change is a different one, the sync is refused rather than spending your approval on something you did not read. An application already holding that revision is a no-op, and a denied sync fails with ArgoCD’s own reason. Nothing is written to git.